pl8-base 0.0.1__tar.gz

pl8_base-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Chen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pl8_base-0.0.1/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: pl8-base
+Version: 0.0.1
+Summary: PL8, a lightweight issue tracker backed by DynamoDB
+Keywords: issue-tracker,dynamodb,aws,lambda
+Author: Daniel Chen
+Author-email: Daniel Chen <danieljnchen@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Dist: boto3~=1.43.40
+Requires-Dist: msgspec~=0.21.1
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/dchenstealth/pl8-base
+Project-URL: Repository, https://github.com/dchenstealth/pl8-base
+Project-URL: Issues, https://github.com/dchenstealth/pl8-base/issues
+Description-Content-Type: text/markdown
+
+# pl8-base
+
+`pl8-base` is the data layer for PL8, a lightweight issue tracker backed by
+DynamoDB. It's a Python library, not a service: it defines PL8's entities
+(`Issue`, `Space`, `IssueBlocker`), its events, and the `BasePL8` manager
+that reads and writes them against a DynamoDB table. It's the source of
+truth for PL8's data model, consumed by the Lambda functions that actually
+run PL8 in AWS.
+
+## Getting started
+
+### Install
+
+```bash
+pip install pl8-base
+```
+
+or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv add pl8-base
+```
+
+### Basic usage
+
+`BasePL8` wraps a `boto3` DynamoDB client and a structured logger. Error
+logging passes arbitrary keyword args through to be merged into the log
+record (e.g. `self.logger.error(msg, item=item)`), which a stdlib
+`logging.Logger` rejects — pass an
+[`aws-lambda-powertools`](https://docs.powertools.aws.dev/lambda/python/latest/)
+`Logger` instead (`pip install aws-lambda-powertools` — it's not a dependency
+of this package, since only your logger instance needs it, not `pl8-base`
+itself). It also expects a table already provisioned with `PK`/`SK` and a
+`GSI1` global secondary index (`GSI1PK`/`GSI1SK`) — see
+[Deploying](#deploying) below.
+
+```python
+import boto3
+from aws_lambda_powertools import Logger
+
+from pl8_base.manager import BasePL8
+from pl8_base.types import IssueStatus
+
+pl8 = BasePL8(
+    dynamodb_client=boto3.client("dynamodb"),
+    table_name="pl8",
+    logger=Logger(),
+)
+
+space = pl8.create_space(
+    space_id="eng",
+    name="Engineering",
+    description="Issues for the engineering team",
+)
+
+issue = pl8.create_issue(
+    space_id="eng",
+    title="Fix login bug",
+    description="Users can't log in on Safari",
+    status=IssueStatus.TODO,
+)
+
+pl8.transition_issue(space_id="eng", issue_id=issue.issue_id,
+                     status=IssueStatus.IN_PROGRESS)
+```
+
+## Deploying
+
+`pl8-base` only talks to a DynamoDB table you already have; it doesn't
+provision or run anything in AWS itself. Work is underway to create other
+repos to scaffold this.

pl8_base-0.0.1/README.md

@@ -0,0 +1,71 @@
+# pl8-base
+
+`pl8-base` is the data layer for PL8, a lightweight issue tracker backed by
+DynamoDB. It's a Python library, not a service: it defines PL8's entities
+(`Issue`, `Space`, `IssueBlocker`), its events, and the `BasePL8` manager
+that reads and writes them against a DynamoDB table. It's the source of
+truth for PL8's data model, consumed by the Lambda functions that actually
+run PL8 in AWS.
+
+## Getting started
+
+### Install
+
+```bash
+pip install pl8-base
+```
+
+or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv add pl8-base
+```
+
+### Basic usage
+
+`BasePL8` wraps a `boto3` DynamoDB client and a structured logger. Error
+logging passes arbitrary keyword args through to be merged into the log
+record (e.g. `self.logger.error(msg, item=item)`), which a stdlib
+`logging.Logger` rejects — pass an
+[`aws-lambda-powertools`](https://docs.powertools.aws.dev/lambda/python/latest/)
+`Logger` instead (`pip install aws-lambda-powertools` — it's not a dependency
+of this package, since only your logger instance needs it, not `pl8-base`
+itself). It also expects a table already provisioned with `PK`/`SK` and a
+`GSI1` global secondary index (`GSI1PK`/`GSI1SK`) — see
+[Deploying](#deploying) below.
+
+```python
+import boto3
+from aws_lambda_powertools import Logger
+
+from pl8_base.manager import BasePL8
+from pl8_base.types import IssueStatus
+
+pl8 = BasePL8(
+    dynamodb_client=boto3.client("dynamodb"),
+    table_name="pl8",
+    logger=Logger(),
+)
+
+space = pl8.create_space(
+    space_id="eng",
+    name="Engineering",
+    description="Issues for the engineering team",
+)
+
+issue = pl8.create_issue(
+    space_id="eng",
+    title="Fix login bug",
+    description="Users can't log in on Safari",
+    status=IssueStatus.TODO,
+)
+
+pl8.transition_issue(space_id="eng", issue_id=issue.issue_id,
+                     status=IssueStatus.IN_PROGRESS)
+```
+
+## Deploying
+
+`pl8-base` only talks to a DynamoDB table you already have; it doesn't
+provision or run anything in AWS itself. Work is underway to create other
+repos to scaffold this.

pl8_base-0.0.1/pyproject.toml

@@ -0,0 +1,55 @@
+[project]
+name = "pl8-base"
+version = "0.0.1"
+description = "PL8, a lightweight issue tracker backed by DynamoDB"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+keywords = [
+    "issue-tracker",
+    "dynamodb",
+    "aws",
+    "lambda",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+dependencies = [
+    "boto3~=1.43.40",
+    "msgspec~=0.21.1",
+]
+
+[[project.authors]]
+name = "Daniel Chen"
+email = "danieljnchen@gmail.com"
+
+[project.urls]
+Homepage = "https://github.com/dchenstealth/pl8-base"
+Repository = "https://github.com/dchenstealth/pl8-base"
+Issues = "https://github.com/dchenstealth/pl8-base/issues"
+
+[dependency-groups]
+dev = [
+    "aws-lambda-powertools~=3.35.0",
+    "moto~=5.2.2",
+    "ruff~=0.16.8",
+    "pytest~=9.1.1",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/test_util.py" = ["FURB157"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+
+[build-system]
+requires = ["uv_build>=0.12.10,<0.13.0"]
+build-backend = "uv_build"

pl8_base-0.0.1/pyproject.toml.orig

@@ -0,0 +1,56 @@
+[project]
+name = "pl8-base"
+version = "0.0.1"
+description = "PL8, a lightweight issue tracker backed by DynamoDB"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Daniel Chen", email = "danieljnchen@gmail.com" }
+]
+requires-python = ">=3.11"
+keywords = ["issue-tracker", "dynamodb", "aws", "lambda"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+dependencies = [
+    "boto3~=1.43.40",
+    "msgspec~=0.21.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/dchenstealth/pl8-base"
+Repository = "https://github.com/dchenstealth/pl8-base"
+Issues = "https://github.com/dchenstealth/pl8-base/issues"
+
+[dependency-groups]
+dev = [
+    "aws-lambda-powertools~=3.35.0",
+    "moto~=5.2.2",
+    "ruff~=0.16.8",
+    "pytest~=9.1.1",
+]
+
+[tool.ruff.lint.per-file-ignores]
+# FURB157 would rewrite Decimal("5") as Decimal(5). The cleanup_decimals
+# tests pair an integral case with a fractional one throughout, and only the
+# integral half of each pair can be rewritten, so taking the fix leaves every
+# pair visually mismatched. The string form also mirrors how boto3 hands
+# these values back.
+"tests/test_util.py" = ["FURB157"]
+
+[tool.pytest.ini_options]
+pythonpath = [
+    "src",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.10,<0.13.0"]
+build-backend = "uv_build"

pl8_base-0.0.1/src/pl8_base/__init__.py

@@ -0,0 +1 @@
+# SPDX-License-Identifier: MIT

pl8_base-0.0.1/src/pl8_base/const.py

@@ -0,0 +1,25 @@
+# SPDX-License-Identifier: MIT
+
+MAX_ISSUE_ID_LEN = 16
+MIN_ISSUE_ID_LEN = 3
+RETRY_ISSUE_ID_COLLISIONS = 5
+
+# Bounded because space_id is caller-supplied and composes both SPACE#{space_id}
+# and ISSUE#{space_id}#{issue_id}. 64 leaves the composite key far inside
+# DynamoDB's 2048 byte limit.
+MAX_SPACE_ID_LEN = 64
+
+# Full-jitter exponential backoff for TransactionConflict retries
+TRANSACT_RETRY_ATTEMPTS = 5
+TRANSACT_RETRY_BASE_DELAY = 0.05
+TRANSACT_RETRY_MAX_DELAY = 1.0
+
+# CancellationReasons code marking a transient transaction conflict
+TRANSACT_CONFLICT_REASON = "TransactionConflict"
+# CancellationReasons code marking a failed ConditionExpression
+CONDITION_FAILED_REASON = "ConditionalCheckFailed"
+# Error code a failed ConditionExpression raises outside a transaction
+CONDITION_FAILED_CODE = "ConditionalCheckFailedException"
+
+# Name of the single GSI on the base table
+GSI1_INDEX_NAME = "GSI1"

pl8_base-0.0.1/src/pl8_base/errors.py

@@ -0,0 +1,86 @@
+# SPDX-License-Identifier: MIT
+
+class DDBError(Exception):
+    """Base class for DDB Issues"""
+
+
+class DDBInternalError(DDBError):
+    """Raised for general service errors"""
+
+
+class DDBCorruptedError(DDBInternalError):
+    """Raised if data read from database is corrupted"""
+
+
+class DDBMissingError(DDBError):
+    """Raised when a requested item does not exist"""
+
+
+class DDBExistsError(DDBError):
+    """Raised when an item already exists"""
+
+
+class DDBArgsError(DDBError):
+    """Raised on invalid arguments passed in"""
+
+
+class DDBIdCollisionError(DDBError):
+    """Raised on ID collision after too many retries"""
+
+
+class DDBTransactionConflictError(DDBError):
+    """Raised on transaction conflict.
+
+    Transient contention. The same request may be retried unchanged; see
+    util.retry_on_transaction_conflict.
+    """
+
+
+class DDBVersionConflictError(DDBError):
+    """Raised when a write's version condition fails.
+
+    The caller's view of the item is stale, so retrying the same request will
+    fail again. The caller must re-read and reapply its change.
+    """
+
+
+class DDBTerminalStatusError(DDBError):
+    """Raised when an operation would move an Issue out of DONE, or would
+    mutate an Issue whose DONE status forbids the change.
+
+    DONE is terminal; see types.enums.IssueStatus for why that rule is
+    load-bearing beyond the product requirement.
+    """
+
+
+class DDBStillBlockedError(DDBError):
+    """Raised when an Issue would be transitioned out of BLOCKED while it
+    still has active IssueBlockers.
+
+    The caller must delete the remaining IssueBlockers first, or wait for the
+    blocking Issues to reach DONE.
+    """
+
+
+class DDBBlockingIssueDoneError(DDBError):
+    """Raised when an IssueBlocker would name a DONE Issue as the blocker.
+
+    A DONE Issue blocks nothing; the relationship would be created already
+    satisfied.
+    """
+
+
+class EventError(Exception):
+    """Base class for event issues"""
+
+
+class EventSendError(EventError):
+    """Raised when EventBridge rejects or fails to accept an event.
+
+    Covers both a failed put_events call and a per-entry failure reported
+    back with FailedEntryCount > 0.
+    """
+
+
+class EventCorruptedError(EventError):
+    """Raised when an event's Detail is missing/unknown type, or malformed"""