EDU 1955: Improve Pub/Sub Python Readme #601
Conversation
|
Warning Rate limit exceeded@franrob-projects has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 14 minutes and 27 seconds before requesting another review. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ⛔ Files ignored due to path filters (1)
📒 Files selected for processing (1)
WalkthroughThe README.md file was completely rewritten, transforming it from a detailed, example-rich document into a brief overview. The new version omits all in-depth usage instructions, code examples, and API details, instead providing a summary of the SDK, supported platforms, deprecation notices, and links to external documentation and support resources. Changes
Assessment against linked issues
Estimated code review effort1 (<30 minutes) Poem
✨ Finishing Touches🧪 Generate unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
franrob-projects
requested review from
VeskeR,
m-hulbert,
owenpearson,
ttypic and
umair-ably
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (8)
README.md (8)
3-3: Use “real-time” instead of “realtime” for consistency
The term “real-time” is typically hyphenated in technical writing.
5-5: Capitalize and align product naming
Change “pub-sub messaging” to “Pub/Sub messaging” to match the product’s official styling.
15-15: Title-case the heading
For consistency, update## Getting startedto
## Getting Started
23-23: Title-case the heading
Update## Supported platformsto
## Supported Platforms
29-31: Clarify table header and content
The second column label “Support” is ambiguous. Consider renaming it to “Supported Versions” or “Python Versions” and drop the redundant “Python” in the cell, e.g.:-| Platform | Support | -|----------|-----------------------| -| Python | Python 3.7+ through 3.13 | +| Platform | Supported Versions | +|----------|-----------------------| +| Python | 3.7+ through 3.13 |
47-49: Rename section and refine wording
Update the heading and sentence for clarity:-## Contribute - -Read the [CONTRIBUTING.md](./CONTRIBUTING.md) guidelines to contribute to Ably. +## Contributing + +Read [CONTRIBUTING.md](./CONTRIBUTING.md) to learn how to contribute to Ably.🧰 Tools
🪛 LanguageTool
[misspelling] ~49-~49: Did you mean “too”?
Context: ...NTRIBUTING.md) guidelines to contribute to Ably. --- ## Support and known issues...(TO_TOO)
53-53: Title-case the heading
Change## Support and known issuesto
## Support and Known Issues
58-58: Hyphenate “real-time” and consider heading level
Either elevate this to an H2 under Known Issues or keep as H3 but update to:-### Full Realtime support unavailable +### Full real-time support unavailable
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
README.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
README.md
[uncategorized] ~43-~43: Although a hyphen is possible, it is not necessary in a compound modifier in which the first word is an adverb that ends in ‘ly’.
Context: ...25. --- ## Releases The CHANGELOG.md contains detail...
(HYPHENATED_LY_ADVERB_ADJECTIVE)
[style] ~43-~43: This adverb was used twice in the sentence. Consider removing one of them or replacing them with a synonym.
Context: ...so view all Ably releases on changelog.ably.com. --- ...
(ADVERB_REPETITION_PREMIUM)
[misspelling] ~49-~49: Did you mean “too”?
Context: ...NTRIBUTING.md) guidelines to contribute to Ably. --- ## Support and known issues...
(TO_TOO)
🪛 markdownlint-cli2 (0.17.2)
README.md
35-35: Blank line inside blockquote
null
(MD028, no-blanks-blockquote)
⏰ Context from checks skipped due to timeout of 90000ms (7)
- GitHub Check: check (3.13)
- GitHub Check: check (3.11)
- GitHub Check: check (3.12)
- GitHub Check: check (3.10)
- GitHub Check: check (3.9)
- GitHub Check: check (3.7)
- GitHub Check: check (3.8)
franrob-projects
changed the title
franrob-projects
changed the title
ttypic
left a comment
ttypic
left a comment
There was a problem hiding this comment.
Everything looks good! let's just keep PyPi badge
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (2)
README.md (2)
38-42: Replace Azure-style admonitions
GitHub does not render[!NOTE]and[!IMPORTANT]blocks. Convert these to standard Markdown blockquotes, for example:> **Note:** This SDK works on Linux, macOS, and Windows with Python 3.7+. > > **Important:** SDK versions < 2.0.0-beta.6 will be deprecated on November 1, 2025.
48-48: Fix the CHANGELOG link path
The root-relative link (/ably/ably-python/blob/main/CHANGELOG.md) will 404. Update to a full GitHub URL or correct relative path, for example:- The [CHANGELOG.md](/ably/ably-python/blob/main/CHANGELOG.md) + The [CHANGELOG.md](https://github.com/ably/ably-python/blob/main/CHANGELOG.md)
🧹 Nitpick comments (2)
README.md (2)
6-10: Consider refining the introduction for clarity
The current intro still uses marketing-heavy language. To align with the PR objective of a concise SDK summary, consider focusing on core functionality and dropping promotional phrasing.
34-36: Adjust table headers for clarity
The table’s “Platform | Support” headers could be misleading since it only lists Python versions. Consider renaming to “Language | Version” or expanding the table to explicitly list OS support.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (1)
images/pythonSDK-github.pngis excluded by!**/*.png
📒 Files selected for processing (1)
README.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
README.md
[uncategorized] ~48-~48: Although a hyphen is possible, it is not necessary in a compound modifier in which the first word is an adverb that ends in ‘ly’.
Context: ...25. --- ## Releases The CHANGELOG.md contains detail...
(HYPHENATED_LY_ADVERB_ADJECTIVE)
[style] ~48-~48: This adverb was used twice in the sentence. Consider removing one of them or replacing them with a synonym.
Context: ...so view all Ably releases on changelog.ably.com. --- ...
(ADVERB_REPETITION_PREMIUM)
[misspelling] ~54-~54: Did you mean “too”?
Context: ...NTRIBUTING.md) guidelines to contribute to Ably. --- ## Support and known issues...
(TO_TOO)
🪛 markdownlint-cli2 (0.17.2)
README.md
40-40: Blank line inside blockquote
null
(MD028, no-blanks-blockquote)
⏰ Context from checks skipped due to timeout of 90000ms (7)
- GitHub Check: check (3.9)
- GitHub Check: check (3.12)
- GitHub Check: check (3.11)
- GitHub Check: check (3.7)
- GitHub Check: check (3.8)
- GitHub Check: check (3.10)
- GitHub Check: check (3.13)
🔇 Additional comments (7)
README.md (7)
12-15: Good external links
The “Find out more” items provide clear pointers to the Pub/Sub docs and examples.
20-24: Getting started section is concise
This section effectively directs users to the Python quickstart guide.
28-32: Supported platforms description is clear
Users are informed how to report compatibility issues and where to find support.
46-46: Releases heading looks good
The “## Releases” section clearly separates release notes from other content.
52-54: Contribute section is straightforward
Linking directly toCONTRIBUTING.mdin the repo is appropriate for new contributors.
58-60: Support section is clear
Directing users to the Ably support page under “Support and known issues” is concise and actionable.
63-67: Document known realtime limitation
The note on “Full Realtime support unavailable” correctly informs users of the SDK’s scope and points them to the MQTT adapter.
franrob-projects
force-pushed
the
EDU-1955-Improve-Pub/Sub-Python-README
branch
from
316d5e4 to
10724ae
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (1)
README.md (1)
37-41: Replace Azure-style[!NOTE]/[!IMPORTANT]blocks with standard MarkdownGitHub ignores these admonition tags and the blank line between them triggers
MD028. Convert them to plain block-quotes to ensure they render correctly.-> [!NOTE] -> This SDK works across all major operating platforms (Linux, macOS, Windows) as long as Python 3.7+ is available. -> -> [!IMPORTANT] -> SDK versions < 2.0.0-beta.6 will be [deprecated](https://ably.com/docs/platform/deprecate/protocol-v1) from November 1, 2025. +> **Note:** This SDK works across all major operating systems (Linux, macOS, Windows) as long as Python 3.7+ is available. +> **Important:** SDK versions earlier than 2.0.0-beta.6 will be [deprecated](https://ably.com/docs/platform/deprecate/protocol-v1) on 1 Nov 2025.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (1)
images/pythonSDK-github.pngis excluded by!**/*.png
📒 Files selected for processing (1)
README.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
README.md
[style] ~53-~53: Using many exclamation marks might seem excessive (in this case: 5 exclamation marks for a text that’s 2479 characters long)
Context: ...ackage: sh pip install ably > [!NOTE] Install [Python](https://www.pytho...
(EN_EXCESSIVE_EXCLAMATION)
[style] ~82-~82: This adverb was used twice in the sentence. Consider removing one of them or replacing them with a synonym.
Context: ...so view all Ably releases on changelog.ably.com. --- ...
(ADVERB_REPETITION_PREMIUM)
🪛 markdownlint-cli2 (0.17.2)
README.md
39-39: Blank line inside blockquote
(MD028, no-blanks-blockquote)
⏰ 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). (7)
- GitHub Check: check (3.7)
- GitHub Check: check (3.8)
- GitHub Check: check (3.11)
- GitHub Check: check (3.13)
- GitHub Check: check (3.10)
- GitHub Check: check (3.12)
- GitHub Check: check (3.9)
🔇 Additional comments (1)
README.md (1)
82-82: CHANGELOG link fixed — looks good
The link now points to the absolute GitHub URL and no longer 404s. ✅
franrob-projects
force-pushed
the
EDU-1955-Improve-Pub/Sub-Python-README
branch
from
da93be7 to
f48aabf
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (2)
README.md (2)
35-35: Align Python version: table says 3.7+, note says 3.8+Two different minimum-version requirements are confusing. Pick one (Ably docs currently state 3.7+).
-Install [Python](https://www.python.org/downloads/) version 3.8 or greater. +Install [Python](https://www.python.org/downloads/) version 3.7 or later.Also applies to: 53-55
37-41: Replace Azure-style admonitions and remove blank line inside block-quote
[!NOTE]/[!IMPORTANT]are an Azure Docs extension that GitHub does not render.
The extra blank line (current line 39) breaks the block-quote and triggers MD028.-> [!NOTE] -> This SDK works across all major operating platforms (Linux, macOS, Windows) as long as Python 3.7+ is available. - -> [!IMPORTANT] -> SDK versions < 2.0.0-beta.6 will be [deprecated](https://ably.com/docs/platform/deprecate/protocol-v1) from November 1, 2025. +> **Note:** This SDK works across all major operating systems (Linux, macOS, Windows) as long as Python 3.7+ is available. +> **Important:** SDK versions < 2.0.0-beta.6 will be [deprecated](https://ably.com/docs/platform/deprecate/protocol-v1) from 1 Nov 2025.
🧹 Nitpick comments (1)
README.md (1)
1-3: Add descriptive alt text and verify image path
images/pythonSDK-github.pngis a relative path; ensure the file exists at repo root and provide meaningful alt text for accessibility, e.g.:- +
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (1)
images/pythonSDK-github.pngis excluded by!**/*.png
📒 Files selected for processing (1)
README.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
README.md
[style] ~53-~53: Using many exclamation marks might seem excessive (in this case: 5 exclamation marks for a text that’s 2479 characters long)
Context: ...ackage: sh pip install ably > [!NOTE] Install [Python](https://www.pytho...
(EN_EXCESSIVE_EXCLAMATION)
🪛 markdownlint-cli2 (0.17.2)
README.md
39-39: Blank line inside blockquote
(MD028, no-blanks-blockquote)
⏰ 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). (7)
- GitHub Check: check (3.11)
- GitHub Check: check (3.9)
- GitHub Check: check (3.12)
- GitHub Check: check (3.8)
- GitHub Check: check (3.10)
- GitHub Check: check (3.13)
- GitHub Check: check (3.7)
| ```python | ||
| # Establish a realtime connection. | ||
| # Explicitly calling connect() is unnecessary unless the autoConnect attribute of the ClientOptions object is false | ||
| client.connect() | ||
|
|
||
| # Close a connection | ||
| await client.close() | ||
|
|
||
| # Send a ping | ||
| time_in_ms = await client.connection.ping() | ||
| # Initialize Ably Realtime client | ||
| async with AblyRealtime('your-ably-api-key', client_id='me') as realtime_client: | ||
| # Wait for connection to be established | ||
| await realtime_client.connection.once_async('connected') | ||
| print('Connected to Ably') | ||
|
|
||
| # Get a reference to the 'test-channel' channel | ||
| channel = realtime_client.channels.get('test-channel') | ||
|
|
||
| # Subscribe to all messages published to this channel | ||
| def on_message(message): | ||
| print(f'Received message: {message.data}') | ||
|
|
||
| await channel.subscribe(on_message) | ||
|
|
||
| # Publish a test message to the channel | ||
| await channel.publish('test-event', 'hello world') | ||
| ``` |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Code sample won’t run as-is
AblyRealtimeis not imported.- The snippet is async but isn’t wrapped in an event-loop runner (
asyncio.run). once_asynchas been renamed tooncein >=2.0 beta clients (double-check).
Minimal runnable example:
+# pip install "ably>=2.0.0b6"
+import asyncio
+from ably import AblyRealtime
+
# Initialize Ably Realtime client
async def main():
async with AblyRealtime('your-ably-api-key', client_id='me') as realtime_client:
await realtime_client.connection.once('connected')
print('Connected to Ably')
@@
await channel.publish('test-event', 'hello world')
-```python
-# Initialize Ably Realtime client
-...
-```
+if __name__ == "__main__":
+ asyncio.run(main())This prevents copy-paste frustration for newcomers.
🤖 Prompt for AI Agents
In README.md lines 60 to 78, the Python code sample is incomplete and won't run
as-is because it lacks the import of AblyRealtime, does not wrap the async code
in an event loop runner, and uses the outdated method once_async. Fix this by
adding the necessary import statement for AblyRealtime, wrapping the async code
inside an async main() function, and running it with asyncio.run(main()) under a
__name__ == "__main__" guard. Also, update the event listener method from
once_async to once to match the current Ably client API.
EDU-1955: Adds getting started EDU-1955: Adds supported platforms EDU-1955: Removes install section EDU-1955: Removes update/migrate section EDU-1955: Removes usage section EDU-1955: Removes resources section EDU-1955: Removes requirements section EDU-1955: Adds releases section EDU-1955: Adds contribute section EDU-1955: Condenses Support section EDU-1955: Adds header image and licence shield EDU-1955: Adds usage examples
franrob-projects
force-pushed
the
EDU-1955-Improve-Pub/Sub-Python-README
branch
from
32ff3d9 to
c67e5b1
Compare
This PR streamlines and refocuses the content of README.md to improve readability, simplify navigation, and make ongoing maintenance easier.
Commits
EDU-1955: Rewrites introduction and overview
EDU-1955: Adds getting started
EDU-1955: Adds supported platforms
EDU-1955: Removes install section
EDU-1955: Removes update/migrate section
EDU-1955: Removes usage sectionEDU-1955: Removes usage section
EDU-1955: Removes requirements section
EDU-1955: Adds releases section
EDU-1955: Adds contribute section
EDU-1955: Condenses Support section
EDU-1955: Adds usage examples
Jira
https://ably.atlassian.net/browse/EDU-1955
Summary by CodeRabbit
Summary by CodeRabbit