# Welcome to Subdivisions
[](https://pypi.org/project/subdivisions/)
[](https://github.com/access55/subdivisions/actions)
[](https://www.python.org)
[](https://conventionalcommits.org)
[](https://github.com/psf/black)
[](https://github.com/pre-commit/pre-commit)
[A55 Python library for PubSub Messaging](https://www.youtube.com/watch?v=EYYdQB0mkEU)
### Install in Project
```toml
# pyproject.toml
# Add in every project which will
# receive or send messages
[tool.subdivisions]
source_name = "ProjectName" # ex.: "Client-Manager"
[tool.poetry.dependencies]
subdivisions = "*"
```
Run `poetry update`
### Usage
#### Send Messages
```python
from subdivisions.client import SubClient
from subdivisions.events import UserEvents
client = SubClient()
client.topic = UserEvents.USER_REGISTERED
client.send({"foo": "bar"})
```
#### Receive Messages
```python
from subdivisions.client import SubClient
from subdivisions.events import UserEvents
client = SubClient()
client.topic = UserEvents.USER_REGISTERED
messages = client.get_messages() # use the ``from_dead_letter=True` to receive Dead Letter messages
# Process messages
client.delete_received_messages()
```
### Full Configuration options
Configure subdivisions options in `pyproject.toml` file, inside `[tool.subdivisions]` table:
```toml
# pyproject.toml
[tool.subdivisions]
aws_region = "us-east-1" # AWS Region
aws_allowed_account = "" # AWS Allowed Account Id for create artifacts / send messages
pub_key = "alias/PubSubKey" # KMS PubSubKey (must be created first)
sqs_tags = [] # SQS tags for new queues. Example [{"foo": "bar"}]
queue_prefix = "" # Prefix for new SQS queues
queue_suffix = "" # Suffix for new SQS queues
queue_max_receive_count = 1000 # SQS MaxReceiveCount setting
sns_prefix = "" # Prefix for new SNS topics
sns_suffix = "" # Suffix for new SNS topics
sns_tags = [] # SNS tags for new topics. Example [{"foo": "bar"}]
event_prefix = "" # Prefix for new Eventbride rules
event_suffix = "" # Suffix for new Eventbride rules
event_tags = [] # Eventbridge tags for new rules. Example [{"foo": "bar"}]
event_bus = "default" # Eventbridge Bus
source_name = "" # Eventbridge default source name. No default, must inform
auto_create_new_topic = true # Auto create new topic if not exists in Eventbridge
auto_remove_from_queue = false # Acknowledge first messages on receive
use_aws_env_vars = true # Use AWS default env vars. If false append "SUBDIVISION_" on env vars. Example: "SUBDIVISION_AWS_ACCESS_KEY_ID"
default_prefix = "a55" # Default prefix for all sns, sqs and rule created
default_suffix = "" # Default suffix for all sns, sqs and rule created
```
All options above can be configured in environment variables. Just append `SUBDIVISIONS_` on name. Example: `SUBDIVISIONS_SOURCE_NAME="my_project"`
### Local Development
For local development, please first clone and install this project:
```shell
git clone git@github.com:access55/subdivisions.git /path/to/project
cd /path/to/project
# Install on WSL/Linux
make install
# Install on Powershell
poetry install
```
#### Example: Adding a new Topic
To avoid different names in different projects for the same topic, (i.e: "client_registered" and
"customer_registered") please add new events using Python Enum on `subdivisions.event` module:
```python
# subdivisions.events
from enum import unique, Enum
@unique
class MyNewEvents(Enum):
MY_NEW_EVENT = "my_new_event"
```
#### Commit using a conventional commit message
To generate a new PyPI version, at least one commit must following the
[Conventional Commit](https://www.conventionalcommits.org/en/v1.0.0/) Specification, when you can
add the `feat:` or `fix:` prefix in your message:
```shell
# Create a new patch event. Ex. 1.0.0 to 1.0.1
git commit -m "fix: Event Bug"
# Create a new minor event. Ex. 1.0.0 to 1.1.0
git commit -m "feat: Add New Event"
# Create a new major event. Ex. 1.0.0 to 2.0.0
git commit -m "feat!: Add New Event \n\nBREAKING CHANGE: API changed"
```
Without a `feat:` or `fix:` prefixed commited message, code will not generate a new PyPI version.
### Using AWS Credentials locally
Subdivisions will use AWS default environment variables. If you need to define another credentials, use the following variables:
```env
SUBDIVISIONS_USE_AWS_ENV_VARS="false"
SUBDIVISIONS_AWS_ACCESS_KEY_ID="your id"
SUBDIVISIONS_AWS_SECRET_ACCESS_KEY="your key"
SUBDIVISIONS_AWS_SESSION_TOKEN="your token" # optional
```
### Using Subdivisions in LOCALSTACK
To use with localstack, you need to activate the sqs, sns, events, and kms services and add them to your .env file:
```env
LOCALSTACK_HOSTNAME_LOCAL="http://localstack:4566"
```
Raw data
{
"_id": null,
"home_page": "https://github.com/access55/subdivisions",
"name": "subdivisions",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7,<4.0",
"maintainer_email": "",
"keywords": "pubsub",
"author": "A55 Tech",
"author_email": "tech@a55.tech",
"download_url": "https://files.pythonhosted.org/packages/d9/06/0935a544c2a501e8eba464b26aa5dc42cc0f409e9cba68549e1da1c57014/subdivisions-1.52.0.tar.gz",
"platform": null,
"description": "# Welcome to Subdivisions\n\n[](https://pypi.org/project/subdivisions/)\n[](https://github.com/access55/subdivisions/actions)\n[](https://www.python.org)\n[](https://conventionalcommits.org)\n[](https://github.com/psf/black)\n[](https://github.com/pre-commit/pre-commit)\n\n[A55 Python library for PubSub Messaging](https://www.youtube.com/watch?v=EYYdQB0mkEU)\n\n### Install in Project\n\n```toml\n\n# pyproject.toml\n# Add in every project which will\n# receive or send messages\n[tool.subdivisions]\nsource_name = \"ProjectName\" # ex.: \"Client-Manager\"\n\n[tool.poetry.dependencies]\nsubdivisions = \"*\"\n```\nRun `poetry update`\n\n### Usage\n#### Send Messages\n```python\nfrom subdivisions.client import SubClient\nfrom subdivisions.events import UserEvents\n\nclient = SubClient()\nclient.topic = UserEvents.USER_REGISTERED\nclient.send({\"foo\": \"bar\"})\n```\n\n#### Receive Messages\n```python\nfrom subdivisions.client import SubClient\nfrom subdivisions.events import UserEvents\n\nclient = SubClient()\nclient.topic = UserEvents.USER_REGISTERED\nmessages = client.get_messages() # use the ``from_dead_letter=True` to receive Dead Letter messages\n# Process messages\nclient.delete_received_messages()\n```\n\n### Full Configuration options\n\nConfigure subdivisions options in `pyproject.toml` file, inside `[tool.subdivisions]` table:\n\n```toml\n# pyproject.toml\n[tool.subdivisions]\naws_region = \"us-east-1\" # AWS Region\naws_allowed_account = \"\" # AWS Allowed Account Id for create artifacts / send messages\npub_key = \"alias/PubSubKey\" # KMS PubSubKey (must be created first)\nsqs_tags = [] # SQS tags for new queues. Example [{\"foo\": \"bar\"}]\nqueue_prefix = \"\" # Prefix for new SQS queues\nqueue_suffix = \"\" # Suffix for new SQS queues\nqueue_max_receive_count = 1000 # SQS MaxReceiveCount setting\nsns_prefix = \"\" # Prefix for new SNS topics\nsns_suffix = \"\" # Suffix for new SNS topics\nsns_tags = [] # SNS tags for new topics. Example [{\"foo\": \"bar\"}]\nevent_prefix = \"\" # Prefix for new Eventbride rules\nevent_suffix = \"\" # Suffix for new Eventbride rules\nevent_tags = [] # Eventbridge tags for new rules. Example [{\"foo\": \"bar\"}]\nevent_bus = \"default\" # Eventbridge Bus\nsource_name = \"\" # Eventbridge default source name. No default, must inform\nauto_create_new_topic = true # Auto create new topic if not exists in Eventbridge\nauto_remove_from_queue = false # Acknowledge first messages on receive\nuse_aws_env_vars = true # Use AWS default env vars. If false append \"SUBDIVISION_\" on env vars. Example: \"SUBDIVISION_AWS_ACCESS_KEY_ID\"\ndefault_prefix = \"a55\" # Default prefix for all sns, sqs and rule created\ndefault_suffix = \"\" # Default suffix for all sns, sqs and rule created\n```\n\nAll options above can be configured in environment variables. Just append `SUBDIVISIONS_` on name. Example: `SUBDIVISIONS_SOURCE_NAME=\"my_project\"`\n\n### Local Development\n\nFor local development, please first clone and install this project:\n\n```shell\ngit clone git@github.com:access55/subdivisions.git /path/to/project\ncd /path/to/project\n\n# Install on WSL/Linux\nmake install\n\n# Install on Powershell\npoetry install\n```\n\n\n#### Example: Adding a new Topic\nTo avoid different names in different projects for the same topic, (i.e: \"client_registered\" and\n\"customer_registered\") please add new events using Python Enum on `subdivisions.event` module:\n\n```python\n# subdivisions.events\nfrom enum import unique, Enum\n\n@unique\nclass MyNewEvents(Enum):\n MY_NEW_EVENT = \"my_new_event\"\n```\n\n#### Commit using a conventional commit message\n\nTo generate a new PyPI version, at least one commit must following the\n[Conventional Commit](https://www.conventionalcommits.org/en/v1.0.0/) Specification, when you can\nadd the `feat:` or `fix:` prefix in your message:\n\n```shell\n# Create a new patch event. Ex. 1.0.0 to 1.0.1\ngit commit -m \"fix: Event Bug\"\n\n# Create a new minor event. Ex. 1.0.0 to 1.1.0\ngit commit -m \"feat: Add New Event\"\n\n# Create a new major event. Ex. 1.0.0 to 2.0.0\ngit commit -m \"feat!: Add New Event \\n\\nBREAKING CHANGE: API changed\"\n```\nWithout a `feat:` or `fix:` prefixed commited message, code will not generate a new PyPI version.\n\n### Using AWS Credentials locally\n\nSubdivisions will use AWS default environment variables. If you need to define another credentials, use the following variables:\n\n```env\nSUBDIVISIONS_USE_AWS_ENV_VARS=\"false\"\nSUBDIVISIONS_AWS_ACCESS_KEY_ID=\"your id\"\nSUBDIVISIONS_AWS_SECRET_ACCESS_KEY=\"your key\"\nSUBDIVISIONS_AWS_SESSION_TOKEN=\"your token\" # optional\n```\n\n### Using Subdivisions in LOCALSTACK\n\nTo use with localstack, you need to activate the sqs, sns, events, and kms services and add them to your .env file:\n\n```env\nLOCALSTACK_HOSTNAME_LOCAL=\"http://localstack:4566\"\n```\n\n",
"bugtrack_url": null,
"license": "GPL-3.0",
"summary": "A55 AWS PubSub Library",
"version": "1.52.0",
"project_urls": {
"Homepage": "https://github.com/access55/subdivisions",
"Repository": "https://github.com/access55/subdivisions"
},
"split_keywords": [
"pubsub"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "56903d8a75ecb5129a5d8869d20e5205039ba5c6d8386a97ee4f6196af5db2d0",
"md5": "e7007e9adcd325b19ad2a5c37c20fb1a",
"sha256": "41bfb654aaca4ec09c47eb2f84857adc14cfb7e04fbebf11ced5f66011843df9"
},
"downloads": -1,
"filename": "subdivisions-1.52.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e7007e9adcd325b19ad2a5c37c20fb1a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7,<4.0",
"size": 17739,
"upload_time": "2023-11-03T17:51:42",
"upload_time_iso_8601": "2023-11-03T17:51:42.736207Z",
"url": "https://files.pythonhosted.org/packages/56/90/3d8a75ecb5129a5d8869d20e5205039ba5c6d8386a97ee4f6196af5db2d0/subdivisions-1.52.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d9060935a544c2a501e8eba464b26aa5dc42cc0f409e9cba68549e1da1c57014",
"md5": "a4a5b4ce5584475b6e9ba5b7733adac9",
"sha256": "4414b434106467d3c11283802d3a80a1f355df5e05ba27132a34ea3474f26a42"
},
"downloads": -1,
"filename": "subdivisions-1.52.0.tar.gz",
"has_sig": false,
"md5_digest": "a4a5b4ce5584475b6e9ba5b7733adac9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7,<4.0",
"size": 16465,
"upload_time": "2023-11-03T17:51:44",
"upload_time_iso_8601": "2023-11-03T17:51:44.586010Z",
"url": "https://files.pythonhosted.org/packages/d9/06/0935a544c2a501e8eba464b26aa5dc42cc0f409e9cba68549e1da1c57014/subdivisions-1.52.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-03 17:51:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "access55",
"github_project": "subdivisions",
"github_not_found": true,
"lcname": "subdivisions"
}
JSON
