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.
