safeuploads 2.1.0__tar.gz → 3.0.0__tar.gz

{safeuploads-2.1.0 → safeuploads-3.0.0}/.agents/skills/safeuploads-library/references/code-standards.md

@@ -1,7 +1,7 @@
 # Code standards
 
 ## Python
-- Python 3.13 syntax (`requires-python = ">=3.13"`): `int | None`, `list[str]`, `dict[str, Any]`; no `typing.Optional/List/Dict`.
+- Python 3.11 syntax and standard library (`requires-python = ">=3.11"`): `int | None`, `list[str]`, `dict[str, Any]`; no `typing.Optional/List/Dict`, and no 3.12+ features such as PEP 695 type parameters, `type` aliases or `typing.override`. The 3.11 CI job is the check.
 - Lines up to 79 characters, enforced by `ruff format` (`line-length = 79`); keep comments and docstrings within it too.
 - Imports grouped stdlib / third-party / local; `TYPE_CHECKING` to avoid cycles.
 - Every module has a top-level docstring.

{safeuploads-2.1.0 → safeuploads-3.0.0}/.agents/skills/safeuploads-library/references/testing.md

@@ -9,7 +9,7 @@
 - Markers are declared in `pyproject.toml` (`unit`, `integration`, `slow`, `performance`, `fuzz`) and run with `--strict-markers`; mark a new test accordingly.
 - Skips need `reason=`.
 - Coverage is branch coverage with `fail_under = 90`; it is a ratchet, raise it when coverage rises and never lower it.
-- Tests are deterministic and offline; a performance test asserts a generous bound, never an exact time.
+- Tests are deterministic and offline; a performance test asserts a generous bound, never an exact time, and is deselected by default (`addopts` in `pyproject.toml`), so run it with `-m performance`.
 - Do not mock a validator to test the orchestrator's decision; run the real one on a small payload.
 
 ## Fuzzing
@@ -18,6 +18,7 @@
 
 ```bash
 uv run pytest tests/validators -v
-uv run pytest -m "not performance and not fuzz"
+uv run pytest -m "not fuzz"
+uv run pytest -m performance
 uv run pytest --cov=safeuploads --cov-report=term-missing
 ```

safeuploads-3.0.0/.github/workflows/mirror.yml

@@ -0,0 +1,41 @@
+name: Mirror to GitLab
+
+on:
+  push:
+
+concurrency:
+  group: gitlab-mirror
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  mirror:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Push full mirror to GitLab
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          GITLAB_TOKEN: ${{ secrets.GITLAB_TOKEN }}
+        # Credentials go in per-host Authorization headers passed through
+        # GIT_CONFIG_* environment variables, so they never appear in a
+        # command line, a remote URL or the mirror's stored git config.
+        run: |
+          set -euo pipefail
+          github_auth="$(printf 'x-access-token:%s' "$GITHUB_TOKEN" | base64 -w0)"
+          gitlab_auth="$(printf 'oauth2:%s' "$GITLAB_TOKEN" | base64 -w0)"
+          echo "::add-mask::${github_auth}"
+          echo "::add-mask::${gitlab_auth}"
+          export GIT_CONFIG_COUNT=2
+          export GIT_CONFIG_KEY_0="http.https://github.com/.extraheader"
+          export GIT_CONFIG_VALUE_0="Authorization: Basic ${github_auth}"
+          export GIT_CONFIG_KEY_1="http.https://gitlab.com/.extraheader"
+          export GIT_CONFIG_VALUE_1="Authorization: Basic ${gitlab_auth}"
+          mirror_dir="$RUNNER_TEMP/safeuploads.git"
+          git clone --mirror \
+            "https://github.com/${GITHUB_REPOSITORY}.git" "$mirror_dir"
+          cd "$mirror_dir"
+          git remote set-url --push origin \
+            "https://gitlab.com/endurain-project/safeuploads.git"
+          git push --mirror

{safeuploads-2.1.0 → safeuploads-3.0.0}/.github/workflows/publish-safeuploads.yml

@@ -70,6 +70,11 @@ jobs:
             exit 1
           fi
 
+      # python-magic needs the libmagic shared library at import time; install it
+      # explicitly instead of relying on the runner image, as the test workflows do.
+      - name: Install system dependencies
+        run: sudo apt-get update && sudo apt-get install -y libmagic1
+
       # The full gate runs on every PR, but a tag can point anywhere in history,
       # so re-run it here: a release must never ship code that does not pass.
       - name: Sync dependencies

{safeuploads-2.1.0 → safeuploads-3.0.0}/.github/workflows/test-matrix-safeuploads.yml

@@ -1,7 +1,7 @@
 name: Test matrix safeuploads
 
 # Portability matrix on top of the fast default `Lint & Test` workflow:
-#   * every supported Python version (3.13, 3.14, 3.15) with the full
+#   * every supported Python version (3.11 to 3.15) with the full
 #     dependency set (dev group + fastapi extra), proving the suite
 #     passes on every Python the package declares support for; and
 #   * a bare `import safeuploads` with only the base dependencies
@@ -40,7 +40,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python: ["3.13", "3.14", "3.15"]
+        python: ["3.11", "3.12", "3.13", "3.14", "3.15"]
     steps:
       - name: Checkout code
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

{safeuploads-2.1.0 → safeuploads-3.0.0}/.gitignore

@@ -15,6 +15,7 @@ site/
 # Python
 __pycache__
 .ruff_cache/
+.mypy_cache/
 .hypothesis/
 
 # Tests

{safeuploads-2.1.0 → safeuploads-3.0.0}/AGENTS.md

@@ -1,6 +1,6 @@
 # safeuploads
 
-Secure file upload validation for Python 3.13+ applications.
+Secure file upload validation for Python 3.11+ applications.
 Catches dangerous filenames, malicious extensions, Windows reserved names, compression bombs, polyglots and unsafe XML before an upload is accepted.
 Runtime dependencies are minimal (`python-magic`, `defusedxml`; FastAPI behind the `fastapi` extra).
 Published to PyPI; the public API is governed by SemVer.
@@ -33,7 +33,7 @@ docs/           Documentation site (mkdocs)
 
 ## Commands
 
-From the repository root (Python 3.13+, `uv`, system `libmagic`):
+From the repository root (Python 3.11+, `uv`, system `libmagic`):
 
 ```bash
 uv sync --dev --extra fastapi
@@ -97,4 +97,4 @@ uv run pytest
 - Never build a filesystem path from an uploaded filename.
 - Logging uses `logging.getLogger(__name__)` and the `SecurityAuditLogger`; never log file contents.
 - Comments and docstrings state what the code does now, not what it used to do.
-- Python 3.13 syntax, 79-character lines (`pyproject.toml`), PEP 257 docstrings with `Args`, `Returns`, `Raises` where applicable.
+- Python 3.11 syntax and standard library (no 3.12+ features), 79-character lines (`pyproject.toml`), PEP 257 docstrings with `Args`, `Returns`, `Raises` where applicable.

{safeuploads-2.1.0 → safeuploads-3.0.0}/CHANGELOG.md

@@ -4,6 +4,41 @@ All notable changes to this project are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.0.0] - 2026-11-05
+
+### Added
+
+- Support for Python 3.11 and 3.12; `requires-python` is now `>=3.11` and CI tests 3.11 to 3.15. A Python version stays supported until its CPython end of life and is dropped in the next minor release after that. The Unicode checks use the running Python's Unicode database, so a character assigned after that database's version is rejected as unassigned (for example U+1FAE8 on 3.11).
+
+### Removed
+
+- **Breaking:** the `ConfigValidationError` alias, deprecated in 2.2.0, is removed from `safeuploads` and `safeuploads.exceptions`. Use `ConfigValidationIssue`.
+
+### Security
+
+- ZIP entry names now get the filename checks a top-level upload gets ([GHSA-jjqv-c38c-fjf3](https://github.com/endurain-project/safeuploads/security/advisories/GHSA-jjqv-c38c-fjf3)). `ZipContentInspector` checked entries only against `ZipThreatCategory.EXECUTABLE_FILES`, `SCRIPT_FILES` and `SYSTEM_FILES`, so an entry such as `invoice.docm`, `a.hta`, `CON.txt` or a name with a right-to-left override was accepted although the same name is rejected as an upload. Each entry name is now checked against `DANGEROUS_UNICODE_CHARS` and the rejected Unicode categories, each path component against `WINDOWS_RESERVED_NAMES`, and a file's base name against `BLOCKED_EXTENSIONS` and `COMPOUND_BLOCKED_EXTENSIONS`, on the NFC and NFKC forms, all taken from `FileSecurityConfig`. A failing entry raises `ZipContentError` with `ZIP_CONTENT_THREAT`.
+- The blocked-extension check ignores trailing dots and spaces, as Windows drops them when it saves a file. A filename such as `run.exe ` or `invoice.docm` followed by U+3000 or U+00A0 (which NFKC folds to a space) was accepted as an upload or a ZIP entry; it is now rejected with `EXTENSION_BLOCKED`.
+
+### Changed
+
+- **Breaking:** the ZIP entry name checks under Security reject archives that 2.2.0 accepted under the default configuration, for example archives with `.docm`, `.xlsm`, `.hta`, `.min.css` or `CON.txt` entries. Uploads and entries whose name ends in a blocked extension followed by spaces, such as `run.exe `, are rejected as well. An entry named `.jar`, `.war` or `.ear` whose content is a ZIP now reports `ZIP_CONTENT_THREAT` first instead of `ZIP_NESTED_ARCHIVE`.
+
+## [2.2.0] - 2026-11-05
+
+### Added
+
+- `ConfigValidationIssue`, exported from `safeuploads` and `safeuploads.exceptions`: the record `validate_instance()` and `validate_configuration()` return and `FileSecurityConfigurationError.errors` carries. It is the same dataclass under a name that does not suggest an exception.
+
+### Deprecated
+
+- `ConfigValidationError` is a deprecated alias of `ConfigValidationIssue` and will be removed in 3.0. Accessing or importing it from `safeuploads` or `safeuploads.exceptions` emits a `DeprecationWarning`; it is no longer in `safeuploads.__all__`. It was never an exception, so `except ConfigValidationError` could not catch anything.
+
+### Changed
+
+- Development: the dev dependency `httpx` is replaced by `httpx2`, which Starlette's `TestClient` now expects.
+- Development: performance tests (`-m performance`) are deselected by default; run them with `pytest -m performance`.
+- CI: the publish workflow installs `libmagic1` explicitly, and the GitLab mirror passes its tokens as HTTP authorization headers through `GIT_CONFIG_*` environment variables instead of embedding them in remote URLs.
+
 ## [2.1.0] - 2026-11-05
 
 ### Added
@@ -207,6 +242,8 @@ Initial release.
 - **MIME type verification:** magic-number validation for common file types.
 - Framework-agnostic async validation, a rich exception hierarchy with machine-readable error codes, secure defaults, and full type hints.
 
+[3.0.0]: https://github.com/endurain-project/safeuploads/compare/v2.2.0...v3.0.0
+[2.2.0]: https://github.com/endurain-project/safeuploads/compare/v2.1.0...v2.2.0
 [2.1.0]: https://github.com/endurain-project/safeuploads/compare/v2.0.0...v2.1.0
 [2.0.0]: https://github.com/endurain-project/safeuploads/compare/v1.1.3...v2.0.0
 [1.1.3]: https://github.com/endurain-project/safeuploads/compare/v1.1.2...v1.1.3

{safeuploads-2.1.0 → safeuploads-3.0.0}/CONTRIBUTING.md

@@ -72,7 +72,7 @@ PRs that are too large to review efficiently will be asked to be split before th
    docs: update the integration checklist
    ```
    Commit subjects and PR titles are validated in CI; see `.agents/skills/conventional-commits/SKILL.md` for the allowed types and scopes.
-5. **Run the checks** from the repository root (Python 3.13+, [uv](https://docs.astral.sh/uv/) and the system `libmagic`):
+5. **Run the checks** from the repository root (Python 3.11+, [uv](https://docs.astral.sh/uv/) and the system `libmagic`):
    ```bash
    uv sync --dev --extra fastapi
    uv run ruff check safeuploads tests examples

{safeuploads-2.1.0 → safeuploads-3.0.0}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.5
 Name: safeuploads
-Version: 2.1.0
+Version: 3.0.0
 Summary: A comprehensive file security system for validating uploads and preventing attacks
 Author-email: João Vitória Silva <joao@endurain.com>
 License: MIT
 License-File: LICENSE.md
-Requires-Python: >=3.13
+Requires-Python: >=3.11
 Requires-Dist: defusedxml<1.0.0,>=0.7.1
 Requires-Dist: python-magic<0.5.0,>=0.4.27
 Provides-Extra: fastapi
@@ -18,11 +18,11 @@ Description-Content-Type: text/markdown
 [![Release](https://img.shields.io/github/v/release/endurain-project/safeuploads?label=release&color=blue)](https://github.com/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/)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://pypi.org/project/safeuploads/)
 [![Docs](https://img.shields.io/badge/docs-safeuploads.endurain.com-blue)](https://safeuploads.endurain.com/)
 [![Stars](https://img.shields.io/github/stars/endurain-project/safeuploads?label=stars&logo=github)](https://github.com/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.
+Secure file upload validation for Python 3.11+ applications. Catches dangerous filenames, malicious extensions, Windows reserved names, and compression-based attacks before you accept an upload.
 
 ## Features
 
@@ -46,6 +46,8 @@ Secure file upload validation for Python 3.13+ applications. Catches dangerous f
 pip install safeuploads
 ```
 
+safeuploads supports Python 3.11 and newer. A Python version stays supported until its CPython end of life and is dropped in the next minor release after that.
+
 For FastAPI integration:
 ```bash
 pip install safeuploads[fastapi]

{safeuploads-2.1.0 → safeuploads-3.0.0}/README.md

@@ -4,11 +4,11 @@
 [![Release](https://img.shields.io/github/v/release/endurain-project/safeuploads?label=release&color=blue)](https://github.com/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/)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://pypi.org/project/safeuploads/)
 [![Docs](https://img.shields.io/badge/docs-safeuploads.endurain.com-blue)](https://safeuploads.endurain.com/)
 [![Stars](https://img.shields.io/github/stars/endurain-project/safeuploads?label=stars&logo=github)](https://github.com/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.
+Secure file upload validation for Python 3.11+ applications. Catches dangerous filenames, malicious extensions, Windows reserved names, and compression-based attacks before you accept an upload.
 
 ## Features
 
@@ -32,6 +32,8 @@ Secure file upload validation for Python 3.13+ applications. Catches dangerous f
 pip install safeuploads
 ```
 
+safeuploads supports Python 3.11 and newer. A Python version stays supported until its CPython end of life and is dropped in the next minor release after that.
+
 For FastAPI integration:
 ```bash
 pip install safeuploads[fastapi]

{safeuploads-2.1.0 → safeuploads-3.0.0}/docs/index.md

@@ -12,7 +12,7 @@
     </a>
 </div>
 
-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.
+Secure file upload validation for Python 3.11+ applications. Catches dangerous filenames, malicious extensions, Windows reserved names, and compression-based attacks before you accept an upload.
 
 ## Features
 

{safeuploads-2.1.0 → safeuploads-3.0.0}/docs/security/architecture.md

@@ -51,7 +51,7 @@ safeuploads/
 | `CompressionSecurityValidator` | Checks compression ratio, uncompressed size, entry count, and nested archive limits, and that the listed entries fill the file exactly. |
 | `XmlSecurityValidator` | Parses XML with `defusedxml`, blocking DTDs and external entities (raises `XmlSecurityError`). |
 | `FitSecurityValidator` | Checks the FIT container: headers, header CRC, data size, CRC-16 per section, and that the sections cover the file exactly. |
-| `ZipContentInspector` | Iterates ZIP entries checking for traversal, executables, scripts, symlinks, and recursive structures. With `allow_nested_archives`, inspects every inner ZIP like the top level. |
+| `ZipContentInspector` | Iterates ZIP entries checking for traversal, executables, scripts, symlinks, and recursive structures, and runs the top-level Unicode, Windows reserved-name and blocked-extension checks on each entry name. With `allow_nested_archives`, inspects every inner ZIP like the top level. |
 | `GzipContentInspector` | Streams gzip decompression, checking ratio and size progressively. |
 | `ContentSecurityInspector` | Scans raw bytes for structurally verified executable headers, web shells, and polyglot patterns (image and activity uploads). |
 | `ResourceMonitor` | Context manager enforcing wall-clock time and peak-RSS memory limits at loop boundaries and on exit. |
@@ -181,7 +181,11 @@ UploadFile
 │    │   ├── Null bytes       │
 │    │   ├── Path traversal   │
 │    │   ├── Absolute paths   │
-│    │   └── Symlinks         │
+│    │   ├── Symlinks         │
+│    │   └── Top-level name   │
+│    │       checks (Unicode, │
+│    │       Windows names,   │
+│    │       blocked exts)    │
 │    ├── Dangerous entry types│
 │    ├── Binary signatures    │
 │    ├── Nested archive magic │
@@ -373,7 +377,7 @@ Exception
 All `FileSecurityError` subclasses carry an `error_code` from
 `ErrorCode` for machine-readable classification.
 `FileSecurityConfigurationError` is separate and exposes its
-`errors` list instead. When no code is passed, the default is:
+`errors` list of `ConfigValidationIssue` records instead. When no code is passed, the default is:
 
 | Exception | Default `ErrorCode` |
 |---|---|

{safeuploads-2.1.0 → safeuploads-3.0.0}/docs/security/threat-model.md

@@ -59,6 +59,11 @@ is `.exe`.
   rejected with `UnicodeSecurityError`; none is stripped. A
   filename containing an emoji ZWJ sequence is therefore
   rejected.
+- Categories come from the running Python's Unicode database
+  (14.0 on Python 3.11, 15.0 on 3.12, 15.1 on 3.13), so a
+  character assigned in a later Unicode version is unassigned
+  (Cn) and rejected on an older Python. Older versions only
+  reject more.
 - The Windows reserved-name and extension checks run on the NFC
   name and on its NFKC form, so fullwidth letters or
   superscript digits cannot disguise `CON`, `COM1` or `.php`.
@@ -99,6 +104,11 @@ improperly.
   files, drivers, themes, and help files.
 - Compound extensions (`.tar.gz`, `.user.js`, `.min.css`) are
   checked via `CompoundExtensionCategory`.
+- Trailing dots and spaces are ignored by the blocked-extension
+  check, because Windows drops them when it saves a file. The
+  check also runs on the NFKC form, so `run.exe ` or
+  `invoice.docm` followed by U+3000 (an ideographic space that
+  NFKC folds to a space) is rejected.
 - Allowed extensions are validated against a configurable
   allowlist per file type.
 
@@ -285,6 +295,32 @@ outside the extraction directory (Zip Slip).
   bypasses (CWE-158). Python's `zipfile` truncates `filename`
   at the first NUL, so the raw name is needed.
 
+### Spoofed or Blocked Entry Names (CWE-184, CWE-434)
+
+**Attack:** A file refused as a standalone upload (a
+macro-enabled Office document, an `.hta`, a name with a
+right-to-left override, `CON.txt`) is wrapped in a ZIP so that a
+host extracting or listing the entries stores it anyway.
+
+**Mitigations:**
+
+- Every entry name gets the filename checks a top-level upload
+  gets, driven by the same `FileSecurityConfig` fields, so a
+  configuration that extends a list covers entries too:
+  - the whole name is checked against `DANGEROUS_UNICODE_CHARS`
+    and the rejected Unicode categories, and its NFKC form must
+    not introduce a path separator or `..`;
+  - every path component is checked against
+    `WINDOWS_RESERVED_NAMES`;
+  - a file's base name is checked against `BLOCKED_EXTENSIONS`
+    (every extension in the name) and
+    `COMPOUND_BLOCKED_EXTENSIONS`.
+- The reserved-name and extension checks run on the NFC name and
+  its NFKC form, after stripping trailing dots and spaces that
+  Windows drops on extraction.
+- A failing name is reported as `ZIP_CONTENT_THREAT`; the message
+  shows the name with control and bidi characters escaped.
+
 ### Executable Content in ZIP
 
 **Attack:** Executables, scripts, system files, or shortcuts
@@ -292,10 +328,11 @@ hidden inside ZIP archives.
 
 **Mitigations:**
 
-- The entry's final extension, after stripping trailing dots
-  and spaces, is checked against
-  `ZipThreatCategory.EXECUTABLE_FILES`, `SCRIPT_FILES`, and
-  `SYSTEM_FILES`.
+- Besides `BLOCKED_EXTENSIONS` (see above), the entry's final
+  extension, after stripping trailing dots and spaces, is checked
+  against `ZipThreatCategory.EXECUTABLE_FILES`, `SCRIPT_FILES`,
+  and `SYSTEM_FILES`, which also cover configuration files such
+  as `.ini`, `.cfg` and `.conf`.
 - Binary content is scanned for executable magic bytes from
   `SuspiciousFilePattern.EXECUTABLE_SIGNATURES`. The first 512
   bytes of each entry are read for this scan.

{safeuploads-2.1.0 → safeuploads-3.0.0}/pyproject.toml

@@ -1,13 +1,13 @@
 [project]
 name = "safeuploads"
-version = "2.1.0"
+version = "3.0.0"
 description = "A comprehensive file security system for validating uploads and preventing attacks"
 authors = [
     {name = "João Vitória Silva",email = "joao@endurain.com"}
 ]
 license = {text = "MIT"}
 readme = "README.md"
-requires-python = ">=3.13"
+requires-python = ">=3.11"
 dependencies = [
     "python-magic>=0.4.27,<0.5.0",
     "defusedxml>=0.7.1,<1.0.0",
@@ -27,7 +27,7 @@ dev = [
     "ty>=0.0.83",
     "types-defusedxml",
     # HTTP stack for the FastAPI multipart integration test
-    "httpx>=0.27,<1.0",
+    "httpx2>=2.16,<3.0",
     "python-multipart>=0.0.9,<1.0",
 ]
 docs = [
@@ -46,7 +46,7 @@ exclude-newer = "7 days"
 
 [tool.ruff]
 line-length = 79
-target-version = "py313"
+target-version = "py311"
 
 [tool.ruff.lint]
 select = [
@@ -118,6 +118,10 @@ addopts = [
     "--strict-markers",
     "--strict-config",
     "-ra",
+    # Benchmarks assert wall-clock bounds that depend on the machine;
+    # run them explicitly with `pytest -m performance`.
+    "-m",
+    "not performance",
     "--cov=safeuploads",
     "--cov-report=term-missing",
     "--cov-report=html",
@@ -151,7 +155,7 @@ exclude_lines = [
 ]
 
 [tool.mypy]
-python_version = "3.13"
+python_version = "3.11"
 incremental = false
 # strict = true enables the full strict bundle, including
 # disallow_any_generics, warn_return_any, disallow_untyped_calls,
@@ -170,7 +174,7 @@ ignore_missing_imports = true
 # ``ty`` runs beside mypy as an advisory, non-blocking CI job (it is pre-1.0);
 # mypy stays the gate. Same scope as ``[tool.mypy]``.
 [tool.ty.environment]
-python-version = "3.13"
+python-version = "3.11"
 
 [tool.ty.src]
 include = ["safeuploads"]

{safeuploads-2.1.0 → safeuploads-3.0.0}/safeuploads/__init__.py

@@ -28,7 +28,7 @@ from .enums import (
 )
 from .exceptions import (
     CompressionSecurityError,
-    ConfigValidationError,
+    ConfigValidationIssue,
     ContentThreatError,
     ErrorCode,
     ExtensionSecurityError,
@@ -95,7 +95,7 @@ __all__ = [
     "SeekableFile",
     "UploadFileProtocol",
     # Exceptions
-    "ConfigValidationError",
+    "ConfigValidationIssue",
     "FileSecurityConfigurationError",
     "ErrorCode",
     "FileSecurityError",

{safeuploads-2.1.0 → safeuploads-3.0.0}/safeuploads/config.py

@@ -11,7 +11,7 @@ from .enums import (
     DangerousExtensionCategory,
     UnicodeAttackCategory,
 )
-from .exceptions import ConfigValidationError, FileSecurityConfigurationError
+from .exceptions import ConfigValidationIssue, FileSecurityConfigurationError
 from .utils import bytes_to_mb
 
 logger = logging.getLogger(__name__)
@@ -23,9 +23,9 @@ def _config_error(
     component: str,
     recommendation: str,
     severity: str = "error",
-) -> ConfigValidationError:
+) -> ConfigValidationIssue:
     """
-    Build a ConfigValidationError with a default severity.
+    Build a ConfigValidationIssue with a default severity.
 
     Centralizes construction so the many validation branches
     share one call shape instead of repeating every field.
@@ -38,9 +38,9 @@ def _config_error(
         severity: Severity level ('error', 'warning', 'info').
 
     Returns:
-        Populated ConfigValidationError instance.
+        Populated ConfigValidationIssue instance.
     """
-    return ConfigValidationError(
+    return ConfigValidationIssue(
         error_type=error_type,
         message=message,
         severity=severity,
@@ -451,7 +451,7 @@ class FileSecurityConfig:
         return None
 
     @classmethod
-    def validate_configuration(cls) -> list[ConfigValidationError]:
+    def validate_configuration(cls) -> list[ConfigValidationIssue]:
         """
         Validate the class-level default configuration.
 
@@ -460,7 +460,7 @@ class FileSecurityConfig:
         """
         return cls._collect_errors(cls, cls.limits)
 
-    def validate_instance(self) -> list[ConfigValidationError]:
+    def validate_instance(self) -> list[ConfigValidationIssue]:
         """
         Validate this instance's configuration.
 
@@ -479,7 +479,7 @@ class FileSecurityConfig:
         cls,
         config: "FileSecurityConfig | type[FileSecurityConfig]",
         limits: SecurityLimits,
-    ) -> list[ConfigValidationError]:
+    ) -> list[ConfigValidationIssue]:
         """
         Run all validation routines for the given configuration.
 
@@ -495,7 +495,7 @@ class FileSecurityConfig:
         Returns:
             List of detected validation errors.
         """
-        errors: list[ConfigValidationError] = []
+        errors: list[ConfigValidationIssue] = []
 
         # Validate limit types first so the range checks below
         # never compare a wrongly typed value.
@@ -530,7 +530,7 @@ class FileSecurityConfig:
     @staticmethod
     def _validate_limit_types(
         limits: SecurityLimits,
-    ) -> list[ConfigValidationError]:
+    ) -> list[ConfigValidationIssue]:
         """
         Validate that every limit holds a value of its declared type.
 
@@ -577,7 +577,7 @@ class FileSecurityConfig:
     @staticmethod
     def _validate_file_size_limits(
         limits: SecurityLimits,
-    ) -> list[ConfigValidationError]:
+    ) -> list[ConfigValidationIssue]:
         """
         Validate the provided file size limits.
 
@@ -708,7 +708,7 @@ class FileSecurityConfig:
     @staticmethod
     def _validate_streaming_limits(
         limits: SecurityLimits,
-    ) -> list[ConfigValidationError]:
+    ) -> list[ConfigValidationIssue]:
         """
         Validate streaming, resource and content scan limits.
 
@@ -788,7 +788,7 @@ class FileSecurityConfig:
     @staticmethod
     def _validate_mime_configurations(
         config: "FileSecurityConfig | type[FileSecurityConfig]",
-    ) -> list[ConfigValidationError]:
+    ) -> list[ConfigValidationIssue]:
         """
         Validate MIME type configurations.
 
@@ -876,7 +876,7 @@ class FileSecurityConfig:
     @staticmethod
     def _validate_extension_configurations(
         config: "FileSecurityConfig | type[FileSecurityConfig]",
-    ) -> list[ConfigValidationError]:
+    ) -> list[ConfigValidationIssue]:
         """
         Validate file extension configurations.
 
@@ -1028,7 +1028,7 @@ class FileSecurityConfig:
     @staticmethod
     def _validate_compression_settings(
         limits: SecurityLimits,
-    ) -> list[ConfigValidationError]:
+    ) -> list[ConfigValidationIssue]:
         """
         Validate the provided compression-related limits.
 
@@ -1240,7 +1240,7 @@ class FileSecurityConfig:
         return errors
 
     @classmethod
-    def _validate_enum_consistency(cls) -> list[ConfigValidationError]:
+    def _validate_enum_consistency(cls) -> list[ConfigValidationIssue]:
         """
         Validate enum categories for emptiness and overlaps.
 
@@ -1345,7 +1345,7 @@ class FileSecurityConfig:
     @staticmethod
     def _validate_cross_dependencies(
         config: "FileSecurityConfig | type[FileSecurityConfig]",
-    ) -> list[ConfigValidationError]:
+    ) -> list[ConfigValidationIssue]:
         """
         Validate cross-field configuration constraints.
 
@@ -1452,7 +1452,7 @@ class FileSecurityConfig:
 
     @staticmethod
     def _report_errors(
-        errors: list[ConfigValidationError], strict: bool
+        errors: list[ConfigValidationIssue], strict: bool
     ) -> None:
         """
         Log validation issues and optionally raise.

{safeuploads-2.1.0 → safeuploads-3.0.0}/safeuploads/exceptions.py

@@ -9,10 +9,14 @@ from enum import StrEnum
 
 
 @dataclass
-class ConfigValidationError:
+class ConfigValidationIssue:
     """
     Configuration validation issue with severity and recommendation.
 
+    A plain record, not an exception: ``validate_instance()`` and
+    ``validate_configuration()`` return a list of them, and
+    ``FileSecurityConfigurationError.errors`` carries them.
+
     Attributes:
         error_type: Type of the validation error.
         message: Human-readable error message.
@@ -33,13 +37,13 @@ class FileSecurityConfigurationError(Exception):
     Configuration validation failed with aggregated errors.
 
     Args:
-        errors: List of ConfigValidationError instances.
+        errors: List of ConfigValidationIssue instances.
 
     Attributes:
         errors: List of validation errors that caused failure.
     """
 
-    def __init__(self, errors: list[ConfigValidationError]):
+    def __init__(self, errors: list[ConfigValidationIssue]):
         """Initialize with validation errors."""
         self.errors = errors
         error_messages = [
@@ -49,7 +53,7 @@ class FileSecurityConfigurationError(Exception):
             f"Configuration validation failed: {'; '.join(error_messages)}"
         )
 
-    def __reduce__(self) -> tuple[type, tuple[list[ConfigValidationError]]]:
+    def __reduce__(self) -> tuple[type, tuple[list[ConfigValidationIssue]]]:
         """Rebuild from ``errors`` so pickling round-trips."""
         return (type(self), (self.errors,))