safeuploads 1.0.0__tar.gz → 1.0.1__tar.gz

safeuploads-1.0.1/.forgejo/scripts/check_conventional_commits.py

@@ -0,0 +1,163 @@
+#!/usr/bin/env python3
+"""Validate that messages follow the Conventional Commits 1.0.0 specification.
+
+Reads one or more messages (either from CLI arguments or, when ``--stdin`` is
+passed, one message per line from standard input) and exits non-zero if any of
+them is invalid.
+
+Spec reference: https://www.conventionalcommits.org/en/v1.0.0/
+
+Usage::
+
+    check_conventional_commits.py "feat(api): add endpoint"
+    git log --format=%s base..head | check_conventional_commits.py --stdin
+
+Designed to run with the Python interpreter already available on the Forgejo
+runner image. Uses only the standard library so there is no third-party
+supply-chain surface.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from collections.abc import Iterable
+
+# Allowed types. This whitelist is a *project policy* layered on top of the
+# Conventional Commits 1.0.0 spec (the spec recommends but does not mandate a
+# fixed set of types). Keep this list in sync with the project's commit
+# conventions documented in ``.github/copilot-instructions.md``.
+#
+# Per the spec, types are matched case-insensitively.
+ALLOWED_TYPES: tuple[str, ...] = (
+    "build",
+    "chore",
+    "ci",
+    "docs",
+    "feat",
+    "fix",
+    "perf",
+    "refactor",
+    "revert",
+    "style",
+    "test",
+)
+
+# Subject pattern: ``type(scope)!: description``. Scope and ``!`` are optional.
+# Per CC 1.0.0:
+#   - the type is a noun (matched case-insensitively against ALLOWED_TYPES);
+#   - the scope is any noun describing a section of the codebase, enclosed in
+#     parentheses, so we accept any non-empty string that is not a closing
+#     parenthesis;
+#   - the description is free-form text.
+_HEADER_RE = re.compile(
+    r"""
+    ^
+    (?P<type>[A-Za-z]+)
+    (?:\((?P<scope>[^)]+)\))?
+    (?P<breaking>!)?
+    :\ 
+    (?P<description>.+?)
+    \s*$
+    """,
+    re.VERBOSE,
+)
+
+
+def _validate_message(message: str) -> list[str]:
+    """Return a list of validation errors for ``message`` (empty if valid)."""
+    errors: list[str] = []
+
+    # Conventional Commits only constrains the first line (the header).
+    header = message.splitlines()[0] if message else ""
+
+    if not header.strip():
+        return ["message is empty"]
+
+    match = _HEADER_RE.match(header)
+    if match is None:
+        errors.append(
+            "header does not match '<type>(<scope>)!: <description>' "
+            "(see https://www.conventionalcommits.org/en/v1.0.0/)"
+        )
+        return errors
+
+    commit_type = match.group("type")
+
+    # Project policy: restrict to a known set of types. Types are matched
+    # case-insensitively per the Conventional Commits spec.
+    if commit_type.lower() not in ALLOWED_TYPES:
+        errors.append(
+            f"type '{commit_type}' is not allowed; "
+            f"use one of: {', '.join(ALLOWED_TYPES)}"
+        )
+
+    return errors
+
+
+def _safe_log_value(value: str) -> str:
+    """Return ``value`` escaped for safe CI log output."""
+    return value.encode("unicode_escape").decode("ascii")
+
+
+def _iter_messages(args: argparse.Namespace) -> Iterable[str]:
+    if args.stdin:
+        for line in sys.stdin:
+            stripped = line.rstrip("\n")
+            if stripped:
+                yield stripped
+    else:
+        yield from args.messages
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Validate Conventional Commits headers.",
+    )
+    parser.add_argument(
+        "messages",
+        nargs="*",
+        help="One or more commit messages (or PR titles) to validate.",
+    )
+    parser.add_argument(
+        "--stdin",
+        action="store_true",
+        help="Read messages from standard input, one per line.",
+    )
+    args = parser.parse_args(argv)
+
+    if not args.stdin and not args.messages:
+        parser.error("provide at least one message or use --stdin")
+
+    failures = 0
+    checked = 0
+    for message in _iter_messages(args):
+        checked += 1
+        errors = _validate_message(message)
+        safe_message = _safe_log_value(message)
+        if errors:
+            failures += 1
+            print(f"INVALID: {safe_message}", file=sys.stderr)
+            for err in errors:
+                print(f"  - {err}", file=sys.stderr)
+        else:
+            print(f"OK: {safe_message}")
+
+    if checked == 0:
+        print("No messages to validate.", file=sys.stderr)
+        return 1
+
+    if failures:
+        print(
+            f"\n{failures} of {checked} message(s) failed Conventional Commits "
+            "validation.",
+            file=sys.stderr,
+        )
+        return 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

safeuploads-1.0.1/.forgejo/workflows/conventional-commits.yml

@@ -0,0 +1,44 @@
+name: Conventional Commits
+
+on:
+  pull_request:
+    types: [opened, edited, synchronize, reopened]
+
+permissions:
+  contents: read
+  pull-requests: read
+
+concurrency:
+  group: ${{ forgejo.workflow }}-${{ forgejo.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  validate:
+    runs-on: codeberg-small
+
+    steps:
+      - name: Checkout code
+        uses: https://data.forgejo.org/actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Validate PR title
+        # The PR title is passed through an environment variable to prevent
+        # shell injection via crafted titles (see security-and-owasp guidelines).
+        env:
+          PR_TITLE: ${{ forgejo.event.pull_request.title }}
+        run: |
+          python3 .forgejo/scripts/check_conventional_commits.py "$PR_TITLE"
+
+      - name: Validate commits in PR
+        # Validates every commit subject between the PR base and head. Use the
+        # base/head SHAs from the event payload so we don't depend on the local
+        # checkout ref layout.
+        env:
+          BASE_SHA: ${{ forgejo.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ forgejo.event.pull_request.head.sha }}
+        run: |
+          set -euo pipefail
+          git fetch --no-tags origin "$BASE_SHA" "$HEAD_SHA"
+          git log --format=%s "$BASE_SHA".."$HEAD_SHA" \
+            | python3 .forgejo/scripts/check_conventional_commits.py --stdin

safeuploads-1.0.1/.forgejo/workflows/docs.yml

@@ -0,0 +1,51 @@
+name: Deploy documentation
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+      - master
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'safeuploads/**/*.py'
+      - '.forgejo/workflows/docs.yml'
+
+permissions:
+  contents: write
+
+concurrency:
+  group: ${{ forgejo.workflow }}-${{ forgejo.ref }}
+  cancel-in-progress: true
+
+jobs:
+
+  deploy:
+
+    runs-on: codeberg-small
+
+    steps:
+      - name: Checkout code
+        uses: https://data.forgejo.org/actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: https://data.forgejo.org/actions/setup-python@v5
+        with:
+          python-version: '3.13'
+          cache: pip
+
+      - name: Install documentation dependencies
+        run: pip install mkdocs-material mkdocstrings[python]
+
+      - name: Build documentation
+        run: mkdocs build --site-dir site
+
+      - name: Deploy documentation to Codeberg Pages
+        uses: https://codeberg.org/git-pages/action@v2
+        with:
+          site: https://${{ forge.repository_owner }}.codeberg.page/${{ forge.event.repository.name }}/
+          token: ${{ forge.token }}
+          source: site/

safeuploads-1.0.1/.forgejo/workflows/fuzz.yml

@@ -0,0 +1,44 @@
+name: Scheduled Fuzz
+
+on:
+  schedule:
+    # Every Sunday at 03:00 UTC
+    - cron: "0 3 * * 0"
+  workflow_dispatch:
+
+# Cancel in-progress runs for the same branch to avoid wasted
+# runner minutes.
+concurrency:
+  group: ${{ forge.workflow }}-${{ forge.ref }}
+  cancel-in-progress: true
+
+jobs:
+  fuzz:
+    name: Fuzz
+    runs-on: codeberg-medium-lazy
+
+    steps:
+      - name: Checkout repository
+        uses: https://data.forgejo.org/actions/checkout@v4
+
+      - name: Install system dependencies
+        run: sudo apt-get update && sudo apt-get install -y libmagic1
+
+      - name: Set up Python 3.13
+        uses: https://data.forgejo.org/actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install uv
+        run: pip install uv
+
+      - name: Install dependencies
+        run: uv sync --frozen --dev
+
+      - name: Run fuzz tests
+        run: >
+          uv run pytest -m fuzz
+          --hypothesis-seed=0
+          -x
+          --tb=short
+          -q

safeuploads-1.0.1/.forgejo/workflows/lint-and-test.yml

@@ -0,0 +1,86 @@
+name: Lint & Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+# Cancel in-progress runs for the same branch/PR to avoid wasted
+# runner minutes and race conditions on shared resources.
+concurrency:
+  group: ${{ forge.workflow }}-${{ forge.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # ----------------------------------------------------------------
+  # Lint
+  # Runs ruff on all Python sources. Fails fast so test job is only
+  # triggered when the code is clean.
+  # ----------------------------------------------------------------
+  lint:
+    name: Lint
+    runs-on: codeberg-tiny
+
+    steps:
+      - name: Checkout repository
+        uses: https://data.forgejo.org/actions/checkout@v4
+
+      - name: Set up Python 3.13
+        uses: https://data.forgejo.org/actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install uv
+        run: pip install uv
+
+      - name: Install dependencies
+        run: uv sync --frozen --dev
+
+      - name: Lint with ruff
+        run: uv run ruff check safeuploads tests examples
+
+      - name: Check formatting with ruff
+        run: uv run ruff format --check safeuploads tests examples
+
+  # ----------------------------------------------------------------
+  # Test
+  # Runs the full pytest suite with coverage. Only runs after lint
+  # passes so we don't waste runner minutes on broken code.
+  # ----------------------------------------------------------------
+  test:
+    name: Test
+    runs-on: codeberg-medium
+    needs: lint
+
+    steps:
+      - name: Checkout repository
+        uses: https://data.forgejo.org/actions/checkout@v4
+
+      - name: Install system dependencies
+        run: sudo apt-get update && sudo apt-get install -y libmagic1
+
+      - name: Set up Python 3.13
+        uses: https://data.forgejo.org/actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install uv
+        run: pip install uv
+
+      - name: Install dependencies
+        run: uv sync --frozen --dev
+
+      - name: Audit Python dependencies
+        run: uvx pip-audit --require-hashes --disable-pip -r <(uv export --frozen --no-header --no-emit-project --no-dev)
+
+      - name: Run tests with coverage
+        run: uv run pytest --cov-fail-under=90
+
+      - name: Upload coverage report
+        uses: https://data.forgejo.org/forgejo/upload-artifact@v4
+        if: always()
+        with:
+          name: safeuploads-coverage
+          path: .coverage
+          retention-days: 7

safeuploads-1.0.1/.forgejo/workflows/publish.yml

@@ -0,0 +1,63 @@
+name: Publish to PyPI
+
+on:
+  workflow_dispatch:
+    inputs:
+      confirm:
+        description: "Type the package version to confirm publish"
+        required: true
+        type: string
+
+# Only one publish at a time.
+concurrency:
+  group: publish
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    name: Build & Publish
+    runs-on: codeberg-medium
+
+    steps:
+      - name: Checkout repository
+        uses: https://data.forgejo.org/actions/checkout@v4
+
+      - name: Verify version matches input
+        run: |
+          PKG_VERSION=$(python3 -c "
+          import tomllib, pathlib
+          data = tomllib.loads(
+              pathlib.Path('pyproject.toml').read_text()
+          )
+          print(data['project']['version'])
+          ")
+          if [ "$PKG_VERSION" != "${{ inputs.confirm }}" ]; then
+            echo "::error::Input version ${{ inputs.confirm }} does not match pyproject.toml version $PKG_VERSION"
+            exit 1
+          fi
+          echo "Publishing version $PKG_VERSION"
+
+      - name: Install system dependencies
+        run: sudo apt-get update && sudo apt-get install -y libmagic1
+
+      - name: Set up Python 3.13
+        uses: https://data.forgejo.org/actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install uv
+        run: pip install uv
+
+      - name: Install dependencies
+        run: uv sync --frozen --dev
+
+      - name: Run tests before publish
+        run: uv run pytest --cov-fail-under=90
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
+        run: uv publish

safeuploads-1.0.1/.forgejo/workflows/renovate.yml

@@ -0,0 +1,37 @@
+name: Dependency updates
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '0 4 * * 0'
+
+permissions:
+  contents: write
+  pull-requests: write
+  issues: write
+
+concurrency:
+  group: ${{ forgejo.workflow }}-${{ forgejo.ref }}
+  cancel-in-progress: false
+
+jobs:
+
+  renovate:
+
+    runs-on: codeberg-small
+
+    steps:
+      - name: Checkout code
+        uses: https://data.forgejo.org/actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Renovate
+        uses: docker://ghcr.io/renovatebot/renovate:latest
+        env:
+          LOG_LEVEL: info
+          RENOVATE_CONFIG_FILE: renovate.json
+          RENOVATE_ENDPOINT: https://codeberg.org/api/v1/
+          RENOVATE_PLATFORM: gitea
+          RENOVATE_REPOSITORIES: ${{ forgejo.repository }}
+          RENOVATE_TOKEN: ${{ secrets.RENOVATE_TOKEN }}

{safeuploads-1.0.0 → safeuploads-1.0.1}/.github/copilot-instructions.md

@@ -70,3 +70,24 @@ class MyClass:
 ## Documentation & Examples
 - Update docstrings and README examples when public APIs change (e.g., `FileValidator`, utility helpers).
 - Demonstrate usage snippets with async FastAPI context where applicable.
+
+## Commits logic
+
+Committing should use clear messages following [Conventional Commits](https://www.conventionalcommits.org/) format:
+
+**Format:** `<type>(<scope>)!: <description>` — `(<scope>)` and the breaking-change `!` are optional.
+
+The following rules are enforced automatically on every PR (against the PR title and every commit subject) by `.forgejo/workflows/conventional-commits.yml`. Validation follows the [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/) spec, with a single project-policy addition (the allowed-type whitelist). Generated commit messages must comply:
+
+- **Header format:** `<type>(<scope>)!: <description>` — the `(<scope>)` and breaking-change `!` are optional, and a space is required after the colon.
+- **Allowed types (project policy):** `build`, `chore`, `ci`, `docs`, `feat`, `fix`, `perf`, `refactor`, `revert`, `style`, `test`. Types are matched case-insensitively per the spec.
+- **Scope** (optional) is any non-empty string (no parentheses), per the spec.
+- **Description** is free-form text, per the spec (no lowercase requirement, no trailing-period restriction, no length limit).
+- **Breaking changes** are marked with `!` after the type/scope (e.g. `feat(api)!: ...`) or a `BREAKING CHANGE:` footer in the commit body.
+
+Examples:
+- `feat: add GPX max speed parsing`
+- `fix(garmin): handle multi-segment GPX distance correctly`
+- `docs: update development instructions`
+- `test(activities): add regression test for GPX segment handling`
+- `refactor(api)!: rename Activity.distance to total_distance`

{safeuploads-1.0.0 → safeuploads-1.0.1}/.github/workflows/lint&test.yml

@@ -82,7 +82,7 @@ jobs:
         run: uv sync --frozen --dev
 
       - name: Audit Python dependencies
-        run: uvx pip-audit --require-hashes --disable-pip -r <(uv export --frozen --no-header --no-emit-project)
+        run: uvx pip-audit --require-hashes --disable-pip -r <(uv export --frozen --no-header --no-emit-project --no-dev)
 
       - name: Run tests with coverage
         run: uv run pytest --cov-fail-under=90

safeuploads-1.0.1/CONTRIBUTING.md

@@ -0,0 +1,82 @@
+# Contributing to Endurain
+ 
+Thank you for considering contributing to Endurain! Before diving in, please read these guidelines carefully. They exist to make the process sustainable for everyone.
+
+## A Note on Maintainership
+ 
+Endurain is maintained by a single person in their spare time. This means review bandwidth is genuinely limited. Following these guidelines isn't bureaucracy, it's what allows contributions to actually get merged rather than sitting in a queue indefinitely.
+
+## Before You Write Any Code
+ 
+**Open an issue first.** For anything beyond a small bug fix, typo, or documentation improvement, please open an issue and wait for a response before writing code. This takes minutes and can save you hours of work on something that won't be merged because it conflicts with planned direction, existing work, or project scope.
+ 
+If an issue already exists, comment on it to signal your intent so work isn't duplicated.
+
+## Pull Request Size — The Most Important Rule
+ 
+**Keep PRs small and focused on a single concern.**
+ 
+As a rule of thumb:
+ 
+- **Target under 300 lines changed** (excluding lock files, generated code, and migrations)
+- **One PR = one thing.** Don't bundle a bug fix with a refactor with a new feature
+- If your change is naturally large (e.g. a new integration), break it into a chain of smaller PRs that can each be reviewed and merged independently
+
+PRs that are too large to review efficiently will be asked to be split before they receive a review. This isn't a judgment on the quality of the work, it's a maintainability constraint.
+ 
+**Excluded from the line count:** `uv.lock`, migration files, and other generated or vendored files.
+
+## How to Contribute
+ 
+### Bug Fixes
+
+- Check if an issue already exists before opening a new one
+- Include clear steps to reproduce in the issue
+- Small, targeted fixes are the fastest path to a merge
+
+### Documentation
+
+- Always welcome and rarely requires prior discussion
+- Improvements to the docs site, inline code comments, and the README all count
+- Keep the same tone and structure as existing docs
+
+### New Features
+
+- **Always discuss in an issue first** — this is required, not optional
+- Features that haven't been discussed and approved in an issue may be closed without review, regardless of quality
+
+### Refactors and Code Quality
+
+- Must be discussed in an issue first
+- Pure refactor PRs (no behaviour change) are easiest to review. Keep them separate from feature or fix PRs
+- Include a clear explanation of what improved and why
+
+
+## Getting Started
+ 
+1. **Fork the repository** on Codeberg
+2. **Clone your fork** locally:
+   ```bash
+   git clone https://codeberg.org/YOUR_USERNAME/endurain.git
+   ```
+3. **Create a branch** and use a descriptive name:
+   ```bash
+   git checkout -b fix/garmin-sync-timeout
+   # or
+   git checkout -b feat/gpx-export
+   ```
+4. **Make your changes**, committing with clear messages following [Conventional Commits](https://www.conventionalcommits.org/):
+   ```
+   fix: handle timeout on Garmin sync
+   feat: add GPX export for activities
+   docs: clarify Docker environment variables
+   ```
+5. **Push and open a PR** against the `master` branch, filling in the PR template completely
+
+## Response Time Expectations
+ 
+Reviews may take days to weeks depending on availability. A PR sitting without a response is not a rejection. Please feel free to leave a polite ping after two weeks if there's been no activity.
+
+## Thank You
+ 
+Even small contributions make a real difference. Thank you for taking the time to improve Endurain for everyone who self-hosts it.

{safeuploads-1.0.0 → safeuploads-1.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: safeuploads
-Version: 1.0.0
+Version: 1.0.1
 Summary: A comprehensive file security system for validating uploads and preventing attacks
 Author-email: João Vitória Silva <joao@endurain.com>
 License: MIT
@@ -14,9 +14,13 @@ Description-Content-Type: text/markdown
 
 # safeuploads
 
-![License](https://img.shields.io/github/license/endurain-project/safeuploads)
-[![GitHub release](https://img.shields.io/github/v/release/endurain-project/safeuploads)](https://github.com/endurain-project/safeuploads/releases)
-[![GitHub stars](https://img.shields.io/github/stars/endurain-project/safeuploads.svg?style=social&label=Star)](https://github.com/endurain-project/safeuploads/stargazers)
+[![License](https://img.shields.io/badge/license-MIT-green)](https://codeberg.org/endurain-project/safeuploads/src/branch/main/LICENSE.md)
+[![Release](https://img.shields.io/badge/dynamic/json?url=https://codeberg.org/api/v1/repos/endurain-project/safeuploads/releases/latest&query=$.tag_name&label=release&color=blue)](https://codeberg.org/endurain-project/safeuploads/releases)
+[![PyPI version](https://img.shields.io/pypi/v/safeuploads)](https://pypi.org/project/safeuploads/)
+[![PyPI downloads](https://img.shields.io/pypi/dm/safeuploads)](https://pypi.org/project/safeuploads/)
+[![Python](https://img.shields.io/badge/python-3.13%2B-blue)](https://pypi.org/project/safeuploads/)
+[![Docs](https://img.shields.io/badge/docs-endurain--project.codeberg.page-blue)](https://endurain-project.codeberg.page/safeuploads/)
+[![Stars](https://img.shields.io/badge/dynamic/json?url=https://codeberg.org/api/v1/repos/endurain-project/safeuploads&query=$.stars_count&label=stars&logo=codeberg)](https://codeberg.org/endurain-project/safeuploads)
 
 Secure file upload validation for Python 3.13+ applications. Catches dangerous filenames, malicious extensions, Windows reserved names, and compression-based attacks before you accept an upload.
 
@@ -130,13 +134,7 @@ except FileValidationError as err:
 
 ## Documentation
 
-Full documentation is available at the [safeuploads docs site](https://endurain-project.github.io/safeuploads/).
-
-## Sponsors
-
-A huge thank you to the project sponsors! Your support helps keep this project going.
-
-Consider [sponsoring safeuploads on GitHub](https://github.com/sponsors/endurain-project) to ensure continuous development.
+Full documentation is available at the [safeuploads docs site](https://endurain-project.codeberg.page/safeuploads/).
 
 ## License
 
@@ -147,5 +145,5 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 Contributions welcome! See [Contributing Guidelines](CONTRIBUTING.md) for guidelines.
 
 <div align="center">
-  <sub>Built with ❤️ from Portugal | Part of the <a href="https://github.com/endurain-project">Endurain</a> ecosystem</sub>
+  <sub>Built with ❤️ from Portugal | Part of the <a href="https://codeberg.org/endurain-project">Endurain</a> ecosystem</sub>
 </div>