Add package structure to README

README.md

@@ -24,16 +24,15 @@
 
 Code snippet:
 ```python
-from atproto import Client, models
-from atproto_client.utils import TextBuilder
+from atproto import Client, models, client_utils
 
 
 def main():
     client = Client()
     profile = client.login('my-handle', 'my-password')
     print('Welcome,', profile.display_name)
 
-    text = TextBuilder().text('Hello World from ').link('Python SDK', 'https://atproto.blue')
+    text = client_utils.TextBuilder().text('Hello World from ').link('Python SDK', 'https://atproto.blue')
     post = client.send_post(text)
     client.like(models.create_strong_ref(post))
 
@@ -49,16 +48,15 @@ if __name__ == '__main__':
 ```python
 import asyncio
 
-from atproto import AsyncClient, models
-from atproto_client.utils import TextBuilder
+from atproto import AsyncClient, models, client_utils
 
 
 async def main():
     client = AsyncClient()
     profile = await client.login('my-handle', 'my-password')
     print('Welcome,', profile.display_name)
 
-    text = TextBuilder().text('Hello World from ').link('Python SDK', 'https://atproto.blue')
+    text = client_utils.TextBuilder().text('Hello World from ').link('Python SDK', 'https://atproto.blue')
     post = await client.send_post(text)
     await client.like(models.create_strong_ref(post))
 
@@ -137,6 +135,20 @@ Useful links to continue:
 - [List of all methods with documentation](https://atproto.readthedocs.io/en/latest/xrpc_clients/client.html).
 - [Examples of using the methods](https://github.com/MarshalX/atproto/tree/main/examples).
 
+### SDK structure
+
+The SDK is built upon the following components:
+- `atproto` — the package that contains import shortcuts to other packages.
+- `atproto_cli` — the package that contains the CLI tool to generate code.
+- `atproto_client` — the package that contains the XRPC Client, data models, and utils like rich text helper.
+- `atproto_codegen` — the package that contains the code generator of models, clients, and namespaces.
+- `atproto_core` — the package that contains the core of the SDK. Base class of exceptions, tools to work with NSID, AT URI Schemes, CID, and CAR files.
+- `atproto_firehose` — the package that contains the Firehose (data streaming) client and models.
+- `atproto_lexicon` — the package that contains the lexicon parser.
+
+I highly recommend you to use the `atproto` package to import everything that you need. 
+It contains shortcuts to all other packages.
+
 ### Documentation
 
 The documentation is live at [atproto.blue](https://atproto.blue/).

docs/source/readme.content.md

@@ -61,6 +61,21 @@ Useful links to continue:
 - [List of all methods with documentation](https://atproto.readthedocs.io/en/latest/xrpc_clients/client.html).
 - [Examples of using the methods](https://github.com/MarshalX/atproto/tree/main/examples).
 
+### SDK structure
+
+The SDK is built upon the following components:
+- `atproto` — the package that contains import shortcuts to other packages.
+- `atproto_cli` — the package that contains the CLI tool to generate code.
+- `atproto_client` — the package that contains the XRPC Client, data models, and utils like rich text helper.
+- `atproto_codegen` — the package that contains the code generator of models, clients, and namespaces.
+- `atproto_core` — the package that contains the core of the SDK. Base class of exceptions, tools to work with NSID, AT URI Schemes, CID, and CAR files.
+- `atproto_firehose` — the package that contains the Firehose (data streaming) client and models.
+- `atproto_lexicon` — the package that contains the lexicon parser.
+
+I highly recommend you to use the `atproto` package to import everything that you need.
+It contains shortcuts to all other packages.
+
+
 ### Documentation
 
 The documentation is live at [atproto.blue](https://atproto.blue/).

docs/source/readme.md

@@ -6,16 +6,15 @@
 
 Code snippet:
 ```python
-from atproto import Client, models
-from atproto_client.utils import TextBuilder
+from atproto import Client, models, client_utils
 
 
 def main():
     client = Client()
     profile = client.login('my-handle', 'my-password')
     print('Welcome,', profile.display_name)
 
-    text = TextBuilder().text('Hello World from ').link('Python SDK', 'https://atproto.blue')
+    text = client_utils.TextBuilder().text('Hello World from ').link('Python SDK', 'https://atproto.blue')
     post = client.send_post(text)
     client.like(models.create_strong_ref(post))
 
@@ -31,16 +30,15 @@ if __name__ == '__main__':
 ```python
 import asyncio
 
-from atproto import AsyncClient, models
-from atproto_client.utils import TextBuilder
+from atproto import AsyncClient, models, client_utils
 
 
 async def main():
     client = AsyncClient()
     profile = await client.login('my-handle', 'my-password')
     print('Welcome,', profile.display_name)
 
-    text = TextBuilder().text('Hello World from ').link('Python SDK', 'https://atproto.blue')
+    text = client_utils.TextBuilder().text('Hello World from ').link('Python SDK', 'https://atproto.blue')
     post = await client.send_post(text)
     await client.like(models.create_strong_ref(post))
 

examples/send_rich_text.py

@@ -1,5 +1,4 @@
-from atproto import Client
-from atproto_client.utils import TextBuilder
+from atproto import Client, client_utils
 
 # To send links as "link card" or "quote post" look at the advanced_usage/send_embed.py example.
 # There is a more advanced way to send rich text without helper class in the advanced_usage/send_rich_text.py example.
@@ -9,7 +8,7 @@ def main() -> None:
     client = Client()
     client.login('my-handle', 'my-password')
 
-    text_builder = TextBuilder()
+    text_builder = client_utils.TextBuilder()
     text_builder.tag('This is a rich message. ', 'atproto')
     text_builder.text('I can mention ')
     text_builder.mention('account', 'did:plc:kvwvcn5iqfooopmyzvb4qzba')
@@ -20,7 +19,7 @@ def main() -> None:
     client.send_post(text_builder)  # same with send_image method
 
     # Same with chaining:
-    client.send_post(TextBuilder().text('Test msg using ').link('Python SDK', 'https://atproto.blue/'))
+    client.send_post(client_utils.TextBuilder().text('Test msg using ').link('Python SDK', 'https://atproto.blue/'))
 
 
 if __name__ == '__main__':

packages/atproto/__init__.py

@@ -1,4 +1,5 @@
 from atproto_client import AsyncClient, Client, models
+from atproto_client import utils as client_utils
 from atproto_core.car import CAR
 from atproto_core.cid import CID, CIDType
 from atproto_core.nsid import NSID
@@ -13,11 +14,10 @@
 )
 from atproto_firehose import models as firehose_models
 
-__version__ = '0.0.0'  # placeholder. Dynamic version from Git Tag
 __all__ = [
-    '__version__',
     'AsyncClient',
     'Client',
+    'client_utils',
     'models',
     'CAR',
     'CID',

packages/atproto_client/utils/text_builder.py

@@ -24,8 +24,8 @@ class TextBuilder:
     Example:
         Without chaining:
 
-        >>> from atproto_client.utils import TextBuilder
-        >>> text_builder = TextBuilder()
+        >>> from atproto import client_utils
+        >>> text_builder = client_utils.TextBuilder()
         >>> text_builder.tag('This is a rich message. ', 'atproto')
         >>> text_builder.text('I can mention ')
         >>> text_builder.mention('account', 'did:plc:kvwvcn5iqfooopmyzvb4qzba')
@@ -34,16 +34,15 @@ class TextBuilder:
 
         With chaining:
 
-        >>> from atproto_client.utils import TextBuilder
-        >>> text_builder = TextBuilder().text('Test msg using ').link('Python SDK', 'https://atproto.blue/')
+        >>> from atproto import client_utils
+        >>> text_builder = client_utils.TextBuilder().text('Test msg using ').link('Python SDK', 'https://atproto.blue/')
 
         Later you can use this builder in the Client:
 
-        >>> from atproto import Client
-        >>> from atproto_client.utils import TextBuilder
+        >>> from atproto import Client, client_utils
         >>> client = Client()
         >>> # You can pass instance of TextBuilder instead of str to the "text" argument.
-        >>> client.send_post(TextBuilder().link('Python SDK', 'https://atproto.blue/'))
+        >>> client.send_post(client_utils.TextBuilder().link('Python SDK', 'https://atproto.blue/'))
         >>> # Same with send_image method
 
     Note:

test.py

@@ -11,12 +11,12 @@
     AtUri,
     Client,
     FirehoseSubscribeReposClient,
+    client_utils,
     exceptions,
     models,
     parse_subscribe_repos_message,
 )
 from atproto_client.models import get_model_as_dict, get_model_as_json, get_or_create, ids, is_record_type
-from atproto_client.utils import TextBuilder
 
 if t.TYPE_CHECKING:
     from atproto_firehose.models import MessageFrame
@@ -48,24 +48,23 @@ def sync_main() -> None:
 
     post = client.get_post('3k2yihcrp6f2c')
     print(post)
-    exit(0)
-
-    with open('cat2.jpg', 'rb') as f:
-        cat_data = f.read()
-
-    upload = client.upload_blob(cat_data)
-    embed_external = models.AppBskyEmbedExternal.Main(
-        external=models.AppBskyEmbedExternal.External(
-            title='Test title',
-            description='Test description',
-            uri='https://atproto.blue',
-            thumb=upload.blob,
-        )
-    )
 
-    client.send_post('test external with thumb', embed=embed_external)
-
-    exit(0)
+    # with open('cat2.jpg', 'rb') as f:
+    #     cat_data = f.read()
+    #
+    # upload = client.upload_blob(cat_data)
+    # embed_external = models.AppBskyEmbedExternal.Main(
+    #     external=models.AppBskyEmbedExternal.External(
+    #         title='Test title',
+    #         description='Test description',
+    #         uri='https://atproto.blue',
+    #         thumb=upload.blob,
+    #     )
+    # )
+    #
+    # client.send_post('test external with thumb', embed=embed_external)
+    #
+    # exit(0)
 
     post = client.get_post('3k2yihcrp6f2c')
     # print(client.get_posts(['at://did:plc:kvwvcn5iqfooopmyzvb4qzba/app.bsky.feed.post/3k2yihcrp6f2c']))
@@ -90,21 +89,21 @@ def sync_main() -> None:
     # client.unmute('test.marshal.dev'))
     # print(client.resolve_handle('bsky.app'))
     # print(client.upload_blob(b'lol'))
-    exit(0)
+    # exit(0)
 
-    # client.send_post(TextBuilder().text('Test msg using ').link('Python SDK', 'https://atproto.blue/'))
-    # text = TextBuilder().text('Hello World from ').link('atpoto SDK', 'https://atproto.blue')
+    # client.send_post(client_utils.TextBuilder().text('Test msg using ').link('Python SDK', 'https://atproto.blue/'))
+    # text = client_utils.TextBuilder().text('Hello World from ').link('atpoto SDK', 'https://atproto.blue')
     # post = client.send_post(text)
     # print(post)
 
-    text_builder = TextBuilder()
+    text_builder = client_utils.TextBuilder()
     text_builder.tag('This is a rich message. ', 'atproto')
     text_builder.text('I can mention ')
     text_builder.mention('account', 'did:plc:kvwvcn5iqfooopmyzvb4qzba')
     text_builder.text(' and add clickable ')
     text_builder.link('link', 'https://atproto.blue/')
 
-    text_builder = TextBuilder().text('Test msg using ').link('Python SDK', 'https://atproto.blue/')
+    text_builder = client_utils.TextBuilder().text('Test msg using ').link('Python SDK', 'https://atproto.blue/')
 
     client.send_post(text_builder)
 
@@ -188,7 +187,7 @@ async def main() -> None:
     profile = await async_client.login(os.environ['USERNAME'], os.environ['PASSWORD'])
     print(profile)
 
-    # text = TextBuilder().text('Hello World from ').link('Python SDK', 'https://atproto.blue')
+    # text = client_utils.TextBuilder().text('Hello World from ').link('Python SDK', 'https://atproto.blue')
     # await async_client.send_post(text)
 
     # should be async open