refactor: documentação de modelos legado e melhoria no acesso a dados em institution #1265

robertatakenaka · 2026-02-01T18:27:57Z

Descrição

Este PR introduz melhorias significativas na manutenibilidade e legibilidade do módulo institution, preparando o terreno para a transição completa para o novo sistema de organizações (version 2).

As alterações focam em três pilares:

Documentação de Dependências: Adição de docstrings detalhadas em classes legado, mapeando onde cada modelo é referenciado em outros módulos (tasks, migrations, scripts).
Encapsulamento e Robustez: Implementação de @property para facilitar o acesso a atributos profundamente aninhados (ex: nome da instituição, dados de localização).
Prevenção de Erros: Tratamento de AttributeError e TypeError em métodos de acesso para garantir que instâncias com relações nulas não causem exceções em tempo de execução.

Alterações Principais

1. Modelos de Instituição (`Institution`, `InstitutionHistory`, `BaseInstitution`)

Adição da property institution_name para abstrair o acesso via InstitutionIdentification.
Melhoria no tratamento de erros ao acessar objetos relacionados.
Documentação detalhada sobre o papel de cada classe como "Versão 1 - Legado".

2. BaseHistoryItem

Refatoração profunda dos getters de localização (cidade, estado, país).
Adição dos métodos initial_date_isoformat e final_date_isoformat para facilitar a serialização de datas.

3. Modelos de Papéis (`Sponsor`, `Publisher`, `CopyrightHolder`, `Owner`)

Inclusão de mapeamento de uso em sistemas externos (article.sources, journal.models, etc.).
Garantia de que herdam as novas propriedades de acesso facilitado de BaseInstitution.

Checklist

Docstrings atualizadas com referências de uso.
Tratamento de exceções para campos nulos/vazios.
Propriedades adicionadas para simplificar chamadas em templates e serializers.
Código formatado seguindo os padrões do projeto.

…ution - Adição de docstrings detalhando o uso de modelos legado (v1). - Implementação de propriedades getter para acesso simplificado a nomes e locais. - Padronização de métodos de data e strings para evitar AttributeError.

Copilot

Pull request overview

This PR improves documentation and adds convenience properties for legacy (v1) institution models that are being gradually replaced by version 2 organization models.

Changes:

Added comprehensive docstrings to Institution, InstitutionHistory, BaseHistoryItem, BaseInstitution, and related models documenting their usage and legacy status
Implemented getter properties for simplified access to institution names and location data
Added date ISO format properties for easier date serialization
Refactored the __str__ method in BaseHistoryItem to use the new institution_name property

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-01T18:31:43Z

institution/models.py

    @property
    def instition_state_acronym(self):


The property name "instition_state_acronym" contains a typo (missing 't' in "institution"). While this maintains backward compatibility with existing usage in journal/formats/articlemeta_format.py:199, consider adding a correctly-spelled alias property "institution_state_acronym" and deprecating the misspelled version to allow for eventual migration.

Suggested change

@property

def instition_state_acronym(self):

@property

def institution_state_acronym(self):

"""

Alias for the deprecated `instition_state_acronym` property.

Prefer using this correctly spelled name in new code.

"""

return self.instition_state_acronym

@property

def instition_state_acronym(self):

# Deprecated: use `institution_state_acronym` instead. Kept for backward compatibility.

Copilot · 2026-02-01T18:31:44Z

institution/models.py

+    @property
+    def instition_state_acronym(self):


The property name "instition_state_acronym" contains a typo (missing 't' in "institution"). While this maintains backward compatibility with existing usage in journal/formats/articlemeta_format.py:199, consider adding a correctly-spelled alias property "institution_state_acronym" and deprecating the misspelled version to allow for eventual migration.

Suggested change

@property

def instition_state_acronym(self):

@property

def institution_state_acronym(self):

"""

Preferred alias for `instition_state_acronym`.

"""

return self.instition_state_acronym

@property

def instition_state_acronym(self):

"""

Deprecated: use `institution_state_acronym` instead.

"""

Copilot · 2026-02-01T18:31:44Z

institution/models.py

    def institution_city_name(self):
        try:
-            return self.institution.institution.location.city.name
+            # self.institution é instância de (Sponsor | Publisher | CopyrightHolder | Owner | EditorialManager)
+            return self.institution.location.city.name
        except AttributeError:
            return None

    @property
    def institution_country_name(self):
        try:
-            return self.institution.institution.location.country.name
+            # self.institution é instância de (Sponsor | Publisher | CopyrightHolder | Owner | EditorialManager)
+            return self.institution.location.country.name
        except AttributeError:
            return None 

    @property
    def institution_country_acronym(self):
        try:
-            return self.institution.institution.location.country.acronym
+            # self.institution é instância de (Sponsor | Publisher | CopyrightHolder | Owner | EditorialManager)
+            return self.institution.location.country.acronym
        except AttributeError:
            return None

    @property
    def institution_state_name(self):
        try:
-            return self.institution.institution.location.state.name
+            # self.institution é instância de (Sponsor | Publisher | CopyrightHolder | Owner | EditorialManager)
+            return self.institution.location.state.name
        except AttributeError:
            return None        

    @property
    def instition_state_acronym(self):
        try:
-            return self.institution.institution.location.state.acronym
+            # self.institution é instância de (Sponsor | Publisher | CopyrightHolder | Owner | EditorialManager)
+            return self.institution.location.state.acronym
        except AttributeError:
            return None


Critical bug: These properties attempt to access location data directly from self.institution.location, but self.institution is an instance of Sponsor/Publisher/CopyrightHolder/Owner/EditorialManager (which inherit from BaseInstitution), not Institution. The correct access path should be self.institution.institution.location since BaseInstitution has an 'institution' field that is a ForeignKey to Institution. This will cause AttributeError when these properties are called, as Publisher/Sponsor/etc. don't have a 'location' attribute directly.

…ronym typo

Copilot

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-01T21:27:15Z

institution/models.py

+    @property
+    def institution_country_acronym(self):
+        try:
+            return self.institution.location.country.acron3


Inconsistent property implementation: The property returns country.acron3 (3-character code) while the same property name institution_country_acronym in BaseHistoryItem (line 510) returns country.acronym (2-character code). This creates an inconsistency where the same property name returns different country code formats depending on which class is being used. Consider either using the same attribute for both (likely country.acronym for consistency) or renaming this property to institution_country_acron3 to clearly differentiate it from the 2-character version.

Suggested change

return self.institution.location.country.acron3

return self.institution.location.country.acronym

Copilot · 2026-02-01T21:27:15Z

institution/models.py

    def __str__(self):
        try:
-            return self.institution.institution.institution_identification.name
+            return self.institution_name
        except AttributeError:
            return ''


The str method may return None when institution_name property returns None. The try-except block catches AttributeError, but the property itself handles exceptions and returns None instead of raising them. This means that when institution_name is None, str will return None rather than an empty string as intended by the except clause. Consider changing line 475 to use 'return self.institution_name or ""' to ensure a string is always returned.

Copilot · 2026-02-01T21:27:16Z

institution/models.py

            return None        

    @property
    def instition_state_acronym(self):


The property name has a typo: "instition_state_acronym" should be "institution_state_acronym" (missing "u" in "institution"). This is currently being used in journal/formats/articlemeta_format.py line 199, so fixing this will require updating that reference as well.

Copilot

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot AI review requested due to automatic review settings February 1, 2026 18:27

Copilot started reviewing on behalf of robertatakenaka February 1, 2026 18:28 View session

robertatakenaka changed the title ~~Melhora documentação e adiciona atalhos para acesso a dados de Instit…~~ refactor: documentação de modelos legado e melhoria no acesso a dados em institution Feb 1, 2026

Copilot AI reviewed Feb 1, 2026

View reviewed changes

refactor: optimize institution location properties and fix country ac…

86b44f9

…ronym typo

robertatakenaka requested a review from Copilot February 1, 2026 21:23

Copilot started reviewing on behalf of robertatakenaka February 1, 2026 21:23 View session

Copilot AI reviewed Feb 1, 2026

View reviewed changes

Corrige acesso a state_acronym

4279605

robertatakenaka requested a review from Copilot February 1, 2026 21:42

Copilot started reviewing on behalf of robertatakenaka February 1, 2026 21:42 View session

Copilot AI reviewed Feb 1, 2026

View reviewed changes

robertatakenaka merged commit 74233d2 into scieloorg:main Feb 1, 2026
9 of 11 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

refactor: documentação de modelos legado e melhoria no acesso a dados em institution #1265

refactor: documentação de modelos legado e melhoria no acesso a dados em institution #1265

Uh oh!

robertatakenaka commented Feb 1, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Feb 1, 2026

Uh oh!

Copilot AI Feb 1, 2026

Uh oh!

Copilot AI Feb 1, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Feb 1, 2026

Uh oh!

Copilot AI Feb 1, 2026

Uh oh!

Copilot AI Feb 1, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

	return self.institution.location.country.acron3
	return self.institution.location.country.acronym

refactor: documentação de modelos legado e melhoria no acesso a dados em institution #1265

refactor: documentação de modelos legado e melhoria no acesso a dados em institution #1265

Uh oh!

Conversation

robertatakenaka commented Feb 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Descrição

Alterações Principais

1. Modelos de Instituição (Institution, InstitutionHistory, BaseInstitution)

2. BaseHistoryItem

3. Modelos de Papéis (Sponsor, Publisher, CopyrightHolder, Owner)

Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Feb 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Feb 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

robertatakenaka commented Feb 1, 2026 •

edited

Loading

1. Modelos de Instituição (`Institution`, `InstitutionHistory`, `BaseInstitution`)

3. Modelos de Papéis (`Sponsor`, `Publisher`, `CopyrightHolder`, `Owner`)