Improve README examples by adding types - closes #1233

[fizyk]

Chore that needs to be done:

• Add newsfragment pipenv run towncrier create [issue_number].[type].rst

Types are defined in the pyproject.toml, issue_number either from issue tracker or the Pull request number

Summary by CodeRabbit

• Documentation

  • Enhanced code examples with explicit type hints and return annotations for clearer usage guidance
  • Updated example imports and database connection examples for consistency across docs
  • Added a news fragment noting improved code examples to surface in changelogs

• Chores

  • Added configuration to enable documentation-focused changelog fragments

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

README code examples are updated with explicit type hints, added imports, and psycopg replaces psycopg2 for connection examples. A new Towncrier docs fragment and configuration entry are added for documentation changelog items.

Changes

Cohort / File(s)	Summary
Documentation examples README.rst	Added explicit type annotations (e.g., Connection, Session, Iterator, PostgreSQLExecutor, User), updated fixture and test signatures, replaced psycopg2.connect with psycopg.connect, and added corresponding imports.
Changelog infrastructure newsfragments/1233.docs.rst, pyproject.toml	Added a new Towncrier fragment file for docs and registered a docs fragment type in pyproject.toml with showcontent = true.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

• Check README type hints for correct imports and valid annotation syntax.
• Confirm psycopg.connect usage and example connection strings are consistent.
• Verify the new Towncrier fragment section in pyproject.toml follows project conventions.

Poem

🐇 I hopped through README's leafy rows,
Adding types where clear light grows.
Psycopg now hops in place,
Docs dressed up with tidy grace,
A rabbit cheers the tidy prose.

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarises the main change: adding type annotations to README examples, directly corresponding to the primary modifications across README.rst, newsfragments, and pyproject.toml.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch issue-1233

---

📜 Recent review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between f59335a and c83bdf8.

📒 Files selected for processing (3)

• README.rst (11 hunks)
• newsfragments/1233.docs.rst (1 hunks)
• pyproject.toml (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

• newsfragments/1233.docs.rst

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (5)

• GitHub Check: postgresql_oldest / postgres (3.13)
• GitHub Check: postgresql_oldest / postgres (3.10)
• GitHub Check: postgresql_17 / postgres (3.14)
• GitHub Check: docker_postgresql_18 / postgres (3.11)
• GitHub Check: postgresql_17 / postgres (3.12)

🔇 Additional comments (6)

pyproject.toml (1)

116-118: LGTM!

The Documentation fragment configuration follows the established pattern and correctly enables documentation-related changelog entries.

README.rst (5)

311-322: LGTM!

Type annotations are correctly applied with all necessary types available in scope.

---

350-359: LGTM!

All necessary imports are present, and type annotations are correctly applied.

---

384-393: LGTM!

The context manager example has all required imports and correct type annotations.

---

439-446: LGTM!

Type annotations are correct with the necessary Connection import present.

---

501-521: LGTM with minor note.

Iterator is correctly imported, and the psycopg dialect is properly used throughout. Note that line 506 has the same **kwargs: str typing as the earlier example, which may warrant consistency if that's addressed.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 5

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

README.rst (1)

297-297: Update SQLAlchemy dialect to match psycopg v3.

The connection string uses the psycopg2 dialect (postgresql+psycopg2://), which is inconsistent with the imported psycopg (version 3). For psycopg v3, SQLAlchemy uses the psycopg dialect.

Apply this diff:

-connection = f'postgresql+psycopg2://{postgresql.info.user}:@{postgresql.info.host}:{postgresql.info.port}/{postgresql.info.dbname}'
+connection = f'postgresql+psycopg://{postgresql.info.user}:@{postgresql.info.host}:{postgresql.info.port}/{postgresql.info.dbname}'

Note: This issue also appears on lines 502 and 515.

📜 Review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 6cf17b9 and f59335a.

📒 Files selected for processing (3)

• README.rst (11 hunks)
• newsfragments/1233.docs.rst (1 hunks)
• pyproject.toml (1 hunks)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)

• GitHub Check: postgresql_18 / postgres (3.14)
• GitHub Check: postgresql_18 / postgres (3.11)
• GitHub Check: postgresql_18 / postgres (pypy-3.11)
• GitHub Check: postgresql_18 / postgres (3.13)

🔇 Additional comments (5)

newsfragments/1233.docs.rst (1)

1-1: LGTM!

The changelog fragment accurately describes the improvements made to the README examples.

pyproject.toml (1)

116-118: LGTM!

The new documentation fragment configuration is correctly defined and follows the same pattern as existing fragments.

README.rst (3)

310-319: LGTM!

The type annotations for the user fixture are correct and clear.

---

322-332: LGTM!

The test function signature with type annotations is correct and demonstrates proper typing for test functions.

---

435-447: LGTM!

The type annotations and imports for the PostgreSQL Docker test are correct.