chore: initial commit

Author: iyad-f

.dockerignore

@@ -0,0 +1,18 @@
+**/__pycache__/
+**/*.py[cod]
+[!__]_*.py
+**/*.ipynb
+
+.git/
+.github/
+.venv/
+.vscode/
+.gitignore
+.gitmodules
+.env
+
+logs/
+docker-compose.yaml
+Dockerfile
+secrets/
+config/

.editorconfig

@@ -0,0 +1,23 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 4
+
+[*.py]
+max_line_length = 90
+
+[*.pyi]
+max_line_length = 90
+
+[*.md]
+indent_size = 2
+
+[*.toml]
+indent_size = 2
+
+[*.yaml]
+indent_size = 2

.github/CONTRIBUTING.md

@@ -0,0 +1,30 @@
+# Contribution Guide
+
+First off, thanks for taking the time to contribute. It makes the repository substantially better. :+1:
+
+## Setting up the environment
+
+1. Install Astral's [UV](http://docs.astral.sh/uv/), if you haven't already.
+2. Run `uv sync --all-groups` to create a [virtual environment](https://docs.python.org/3/tutorial/venv.html) and install dependencies.
+
+## Good Bug Reports
+
+Please be aware of the following things when filing bug reports.
+
+1. Don't open duplicate issues. Please search your issue to see if it has been asked already. Duplicate issues will be closed.
+2. When filing a bug about exceptions or tracebacks, please include the _complete_ traceback. Without the complete traceback the issue might be **unsolvable** and you will be asked to provide more information.
+3. Make sure to provide enough information to make the issue workable. The issue template will generally walk you through the process, but they are enumerated here as well:
+  - A **summary** of your bug report. This is generally a quick sentence or two to describe the issue in human terms.
+  - Guidance on **how to reproduce the issue**. Ideally, this should have a small code sample that allows us to run and see the issue for ourselves to debug. **Please make sure that the token is not displayed**. If you cannot provide a code snippet, then let us know what the steps were, how often it happens, etc.
+  - Tell us **what you expected to happen**. That way we can meet that expectation.
+  - Tell us **what actually happens**. What ends up happening in reality? It's not helpful to say "it fails" or "it doesn't work". Say _how_ it failed, do you get an exception? Does it hang? How are the expectations different from reality?
+  - Tell us **information about your environment**. What operating system are you running on?
+
+If the bug report is missing this information then it'll take us longer to fix the issue. We will probably ask for clarification, and barring that if no response was given then the issue will be closed.
+
+## Submitting a Pull Request
+
+Submitting a pull request is fairly simple, just make sure it focuses on a single aspect and doesn't manage to have scope creep, and it's probably good to go. It would be incredibly lovely if the style is consistent to that found in the project. This project follows PEP-8 guidelines (mostly) with a column limit of 90.
+There are provided tool rules in `pyproject.toml` for `ruff` and `pyright` when committing here.
+There are actions that run on new PRs and if those checks fail then the PR will not be accepted.
+Pull requests and commits all need to follow the [Conventional Commit format](https://www.conventionalcommits.org)

.github/ISSUE_TEMPLATE/bug_report.yaml

@@ -0,0 +1,57 @@
+name: Bug Report
+description: Report broken or incorrect behaviour
+labels: unconfirmed bug
+body:
+  - type: markdown
+    attributes:
+      value: >
+        Thanks for taking the time to fill out a bug.
+
+        Please note that this form is for bugs only!
+  - type: input
+    attributes:
+      label: Summary
+      description: A simple summary of your bug report
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Reproduction Steps
+      description: >
+        What you did to make it happen.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Minimal Reproducible Code
+      description: >
+        A short snippet of code that showcases the bug.
+      render: python
+  - type: textarea
+    attributes:
+      label: Expected Results
+      description: >
+        What did you expect to happen?
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Actual Results
+      description: >
+        What actually happened?
+    validations:
+      required: true
+  - type: checkboxes
+    attributes:
+      label: Checklist
+      description: >
+        Let's make sure you've properly done due diligence when reporting this issue!
+      options:
+        - label: I have searched the open issues for duplicates.
+          required: true
+        - label: I have shown the entire traceback, if possible.
+          required: true
+  - type: textarea
+    attributes:
+      label: Additional Context
+      description: If there is anything else to say, please do so here.

.github/ISSUE_TEMPLATE/feature_request.yaml

@@ -0,0 +1,38 @@
+name: Feature Request
+description: Suggest a feature for this library
+labels: feature request
+body:
+  - type: input
+    attributes:
+      label: Summary
+      description: >
+        A short summary of what your feature request is.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: The Problem
+      description: >
+        What problem is your feature trying to solve?
+        What becomes easier or possible when this feature is implemented?
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: The Ideal Solution
+      description: >
+        What is your ideal solution to the problem?
+        What would you like this feature to do?
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: The Current Solution
+      description: >
+        What is the current solution to the problem, if any?
+    validations:
+      required: false
+  - type: textarea
+    attributes:
+      label: Additional Context
+      description: If there is anything else to say, please do so here.

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,14 @@
+## Summary
+
+<!-- What is this pull request for? Does it fix any issues? -->
+
+## Checklist
+
+<!-- Put an x inside [ ] to check it, like so: [x] -->
+
+- [ ] If code changes were made then they have been tested.
+  - [ ] I have updated the documentation to reflect the changes.
+- [ ] This PR fixes a submitted GitHub issue.
+- [ ] This PR adds something new (e.g. new method or parameters).
+- [ ] This PR is a breaking change (e.g. methods or parameters removed/renamed)
+- [ ] This PR is **not** a code change (e.g. documentation, README, ...)

.github/workflows/coverage_and_lint.yaml

@@ -0,0 +1,53 @@
+# Credit: https://github.com/AbstractUmbra/Hondana/blob/main/.github/workflows/coverage_and_lint.yaml
+
+name: Type Coverage and Linting
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+    types: [opened, reopened, synchronize]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.13", "3.x"]
+
+    name: "Type Coverage and Linting @ ${{ matrix.python-version }}"
+    steps:
+      - name: "Checkout Repository"
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          activate-environment: true
+
+      - name: Install deps @ ${{ matrix.python-version }}
+        run: |
+          uv sync --locked --all-extras --all-groups
+
+      - name: "Run Pyright @ ${{ matrix.python-version }}"
+        uses: jakebailey/pyright-action@v2
+        with:
+          warnings: false
+          verify-types: "sonyflake"
+          ignore-external: true
+          annotate: ${{ matrix.python-version != '3.x' && 'all' || 'none' }}
+
+      - uses: astral-sh/ruff-action@v3
+
+      - name: Lint
+        run: ruff check .
+
+      - name: Format check
+        run: ruff format --check .

.gitignore

@@ -0,0 +1,24 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Environments
+.venv
+.env
+
+# Secrets
+/secrets/postgres_password.txt
+/secrets/csrf_token.txt
+/secrets/access_token_secret.txt
+/secrets/rate_limit_bucket_encryption_key.txt
+/secrets/rate_limit_bucket_encryption_nonce.txt
+
+# Config
+/config/app.toml
+
+# Logs
+/logs

.python-version

@@ -0,0 +1 @@
+3.13

Dockerfile

@@ -0,0 +1,43 @@
+ARG PYTHON_BASE=3.13-slim-bookworm
+ARG UV_BASE=python3.13-bookworm-slim
+
+FROM ghcr.io/astral-sh/uv:${UV_BASE} AS builder
+
+ENV UV_COMPILE_BYTECODE=1 UV_LINK_MODE=copy UV_PYTHON_DOWNLOADS=0
+
+WORKDIR /project
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
+    --mount=type=bind,source=uv.lock,target=uv.lock \
+    uv sync --frozen --no-install-project --no-dev
+
+COPY --chown=65532:65532 . /project
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --frozen --no-dev
+
+FROM python:${PYTHON_BASE}
+
+LABEL org.opencontainers.image.title="litestar-backend-template" \
+      org.opencontainers.image.version="0.1.0" \
+      org.opencontainers.image.description="A backend template application built with Litestar" \
+      org.opencontainers.image.source="https://github.com/iyad-f/litestar-backend-template" \
+      org.opencontainers.image.licenses="Apache-2.0" \
+      org.opencontainers.image.authors="Iyad"
+
+RUN addgroup --system --gid 65532 nonroot \
+    && adduser --no-create-home --system --uid 65532 --gid 65532 nonroot
+
+USER nonroot:nonroot
+
+WORKDIR /app
+
+COPY --from=builder --chown=nonroot:nonroot /project /app
+
+ENV PATH=/app/.venv/bin:$PATH PYTHONPATH=/app/src
+
+EXPOSE 8000
+
+ENTRYPOINT ["python", "-O", "-m", "app"]
+CMD ["run"]