[Issue 1325]: add python interactive console

api/Makefile

@@ -250,5 +250,8 @@ copy-oracle-data:
 login: start ## Start shell in running container
 	docker exec -it $(APP_NAME) bash
 
+console: ## Start interactive Python console
+	$(PY_RUN_CMD) python3 -i -m src.tool.console.interactive
+
 help: ## Prints the help documentation and info about each command
 	@grep -E '^[/a-zA-Z0-9_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'

api/src/db/models/opportunity_models.py

@@ -81,6 +81,11 @@ def applicant_types(self) -> list[ApplicantType]:
         # Helper method for serialization of the API response
         return [a.applicant_type for a in self.link_applicant_types]
 
+    def __repr__(self):
+        return (f"<Opportunity(opportunity_id={self.opportunity_id}, "
+                f"opportunity_number='{self.opportunity_number}', "
+                f"opportunity_title='{self.opportunity_title}', "
+                f"agency='{self.agency}', category='{self.category}', ")
 
 class OpportunitySummary(Base, TimestampMixin):
     __tablename__ = "opportunity_summary"
@@ -133,6 +138,49 @@ class OpportunitySummary(Base, TimestampMixin):
     updated_by: Mapped[str | None]
     created_by: Mapped[str | None]
 
+    def __repr__(self):
+        def format_attr(value):
+            """Format the attribute to display 'None' or slice if it's a string."""
+            if value is None:
+                return 'None'
+            elif isinstance(value, str):
+                return f"'{value[:25]}...'" if len(value) > 25 else f"'{value}'"
+            else:
+                return value
+
+        return (f"<OpportunitySummary("
+                f"opportunity_id={format_attr(self.opportunity_id)}, "
+                f"opportunity_status='{format_attr(self.opportunity_status)}', "
+                f"summary_description={format_attr(self.summary_description)}, "
+                f"is_cost_sharing={format_attr(self.is_cost_sharing)}, "
+                f"close_date={format_attr(self.close_date)}, "
+                f"close_date_description={format_attr(self.close_date_description)}, "
+                f"post_date={format_attr(self.post_date)}, "
+                f"archive_date={format_attr(self.archive_date)}, "
+                f"unarchive_date={format_attr(self.unarchive_date)}, "
+                f"expected_number_of_awards={format_attr(self.expected_number_of_awards)}, "
+                f"estimated_total_program_funding={format_attr(self.estimated_total_program_funding)}, "
+                f"award_floor={format_attr(self.award_floor)}, "
+                f"award_ceiling={format_attr(self.award_ceiling)}, "
+                f"additional_info_url={format_attr(self.additional_info_url)}, "
+                f"additional_info_url_description={format_attr(self.additional_info_url_description)}, "
+                f"version_number={format_attr(self.version_number)}, "
+                f"modification_comments={format_attr(self.modification_comments)}, "
+                f"funding_category_description={format_attr(self.funding_category_description)}, "
+                f"applicant_eligibility_description={format_attr(self.applicant_eligibility_description)}, "
+                f"agency_code={format_attr(self.agency_code)}, "
+                f"agency_name={format_attr(self.agency_name)}, "
+                f"agency_phone_number={format_attr(self.agency_phone_number)}, "
+                f"agency_contact_description={format_attr(self.agency_contact_description)}, "
+                f"agency_email_address={format_attr(self.agency_email_address)}, "
+                f"agency_email_address_description={format_attr(self.agency_email_address_description)}, "
+                f"can_send_mail={format_attr(self.can_send_mail)}, "
+                f"publisher_profile_id={format_attr(self.publisher_profile_id)}, "
+                f"publisher_user_id={format_attr(self.publisher_user_id)}, "
+                f"updated_by={format_attr(self.updated_by)}, "
+                f"created_by={format_attr(self.created_by)})"
+                f">")
+
 
 class OpportunityAssistanceListing(Base, TimestampMixin):
     __tablename__ = "opportunity_assistance_listing"
@@ -149,6 +197,14 @@ class OpportunityAssistanceListing(Base, TimestampMixin):
     updated_by: Mapped[str | None]
     created_by: Mapped[str | None]
 
+    def __repr__(self):
+        return (f"<OpportunityAssistanceListing("
+                f"opportunity_assistance_listing_id={self.opportunity_assistance_listing_id}, "
+                f"opportunity_id={self.opportunity_id}, "
+                f"assistance_listing_number='{self.assistance_listing_number}', "
+                f"program_title='{self.program_title}', "
+                f"updated_by='{self.updated_by}', "
+                f"created_by='{self.created_by}')>")
 
 class LinkFundingInstrumentOpportunity(Base, TimestampMixin):
     __tablename__ = "link_funding_instrument_opportunity"
@@ -168,6 +224,12 @@ class LinkFundingInstrumentOpportunity(Base, TimestampMixin):
     updated_by: Mapped[str | None]
     created_by: Mapped[str | None]
 
+    def __repr__(self):
+        return (f"<LinkFundingInstrumentOpportunity(opportunity_id={self.opportunity_id}, "
+                f"funding_instrument='{self.funding_instrument}', "
+                f"updated_by='{self.updated_by}', created_by='{self.created_by}')>")
+
+
 
 class LinkFundingCategoryOpportunity(Base, TimestampMixin):
     __tablename__ = "link_funding_category_opportunity"
@@ -187,6 +249,10 @@ class LinkFundingCategoryOpportunity(Base, TimestampMixin):
     updated_by: Mapped[str | None]
     created_by: Mapped[str | None]
 
+    def __repr__(self):
+        return (f"<LinkFundingCategoryOpportunity(opportunity_id={self.opportunity_id}, "
+                f"funding_category='{self.funding_category}', "
+                f"updated_by='{self.updated_by}', created_by='{self.created_by}')>")
 
 class LinkApplicantTypeOpportunity(Base, TimestampMixin):
     __tablename__ = "link_applicant_type_opportunity"
@@ -205,3 +271,8 @@ class LinkApplicantTypeOpportunity(Base, TimestampMixin):
 
     updated_by: Mapped[str | None]
     created_by: Mapped[str | None]
+
+    def __repr__(self):
+        return (f"<LinkApplicantTypeOpportunity(opportunity_id={self.opportunity_id}, "
+                f"applicant_type='{self.applicant_type}', "
+                f"updated_by='{self.updated_by}', created_by='{self.created_by}')>")

api/src/db/models/transfer/topportunity_models.py

@@ -40,3 +40,29 @@ class TransferTopportunity(Base, TimestampMixin):
     last_upd_date: Mapped[date | None]
     creator_id: Mapped[str | None] = mapped_column(VARCHAR(length=200))
     created_date: Mapped[date | None]
+
+    def __repr__(self):
+        def safe_repr(attr):
+            """Safely format the attribute for __repr__, handling None values."""
+            if attr is None:
+                return 'None'
+            elif isinstance(attr, str):
+                return f"'{attr[:50]}...'" if len(attr) > 50 else f"'{attr}'"
+            else:
+                return str(attr)
+
+        return (f"<TransferTopportunity(opportunity_id={safe_repr(self.opportunity_id)}, "
+                f"oppnumber={safe_repr(self.oppnumber)}, "
+                f"opptitle={safe_repr(self.opptitle)}, "
+                f"owningagency={safe_repr(self.owningagency)}, "
+                f"oppcategory={safe_repr(self.oppcategory)}, "
+                f"category_explanation={safe_repr(self.category_explanation)}, "
+                f"is_draft={safe_repr(self.is_draft)}, "
+                f"revision_number={safe_repr(self.revision_number)}, "
+                f"modified_comments={safe_repr(self.modified_comments)}, "
+                f"publisheruid={safe_repr(self.publisheruid)}, "
+                f"publisher_profile_id={safe_repr(self.publisher_profile_id)}, "
+                f"last_upd_id={safe_repr(self.last_upd_id)}, "
+                f"last_upd_date={safe_repr(self.last_upd_date)}, "
+                f"creator_id={safe_repr(self.creator_id)}, "
+                f"created_date={safe_repr(self.created_date)})>")

api/src/tool/console/interactive.py

@@ -0,0 +1,132 @@
+#
+# Interactive console for using database and services.
+#
+# Connects to the database then drops into a Python interactive prompt.
+#
+# Use via the `-i` flag to python, for example:
+#   poetry run python3 -i -m src.tool.console.interactive
+#
+
+from types import ModuleType
+
+import rich
+import rich.panel
+import rich.pretty
+
+import src.adapters.db as db
+import src.db
+import src.db.models
+import src.logging
+import src.util
+import tests.src.db.models.factories
+from src.adapters.db.clients.postgres_client import PostgresDBClient
+from src.adapters.db.clients.postgres_config import get_db_config
+
+INTRO = """
+Simpler Grants Gov Python console
+
+Useful things:
+
+│ db = database session
+│ f = DB factories module
+│ u = utilities module
+│ r = function to reload REPL
+
+Tips:
+★ Tab-completion is available
+★ History is available (use ↑↓ keys)
+★ Use Ctrl+D to exit
+"""
+
+
+def interactive_console() -> dict:
+    """Set up variables and print a introduction message for the interactive console."""
+
+    db_session = connect_to_database()
+
+    print(INTRO.format(**locals()))
+
+    variables = dict()
+    variables.update(vars(src.db.models.opportunity_models))
+    variables.update(vars(src.db.models.lookup_models))
+
+    # This goes after the imports of entire modules, so the console reserved
+    # names (db, fineos, etc) take precedence. This might break some modules
+    # that expect something different under those names.
+    variables.update(locals())
+
+    # DB
+    variables["db_session"] = db_session
+    variables["dbs"] = db_session
+
+    # DB Factories
+    factories_module = tests.src.db.models.factories
+    if isinstance(db_session, db.Session):
+        factories_module._db_session = db_session
+    variables["f"] = tests.src.db.models.factories
+
+    # Easy access to utilities
+    variables["u"] = src.util
+    variables["util"] = src.util
+
+    # Easy reloading of modules imported in REPL, for retrying something after a
+    # code change without dropping out of REPL
+    variables["r"] = reload_repl
+    variables["reload"] = reload_repl
+    variables["reload_module"] = reload_module
+
+    return variables
+
+
+def connect_to_database() -> db.Session | Exception:
+    db_config = get_db_config()
+
+    # errors sometimes dump sensitive info
+    # (since we're doing locally, we don't need to hide)
+    db_config.hide_sql_parameter_logs = False
+    db_session: db.Session | Exception
+    try:
+        db_session = PostgresDBClient(db_config).get_session()
+    except Exception as err:
+        db_session = err
+
+    return db_session
+
+
+def reload_repl() -> None:
+    import importlib
+    from sys import modules
+
+    for module in set(modules.values()):
+        # only reload our code
+        if "<module 'src." not in str(module):
+            continue
+
+        # individual database model modules can be particular in how they are
+        # loaded, so don't automatically reload them
+        if "<module 'src.db.models." in str(module):
+            continue
+
+        # reloading the logging initialization and stuff can cause some issues,
+        # avoid it all for now
+        if "<module 'src.util.logging" in str(module):
+            continue
+
+        try:
+            importlib.reload(module)
+        except:  # noqa: B001
+            # there are some problems that are swept under the rug here
+            pass
+
+
+def reload_module(m: ModuleType) -> None:
+    import importlib
+
+    importlib.reload(m)
+
+
+if __name__ == "__main__":
+    with src.logging.init(__package__):
+        interactive_variables = interactive_console()
+        globals().update(interactive_variables)
+        rich.pretty.install(indent_guides=True, max_length=20, max_string=400)

documentation/api/development.md

@@ -40,6 +40,10 @@ A very simple [docker-compose.yml](../../docker-compose.yml) has been included t
 
 See the [Makefile](../../api/Makefile) for a full list of commands you can run.
 
+The `make console` command initializes a Python REPL environment pre-configured with database connectivity. This allows developers to perform database queries, utilize factories for data generation, and interact with the application's models directly.
+- Writing a query: `dbs.query(Opportunity).all()`
+- Saving some factory generated data to the db: `f.OpportunityFactory.create()`
+
 ## Docker and Native Development
 
 Several components like tests, linting, and scripts can be run either inside of the Docker container, or outside on your native machine.