pytypehintstore 0.0.4__tar.gz

pytypehintstore-0.0.4/.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

pytypehintstore-0.0.4/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    # Both, because the lock is the one part written twice: an open handle on
+    # Windows, an advisory flock on POSIX. A single runner would leave half of
+    # it untested.
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv pip install --system -e ".[dev]"
+      - run: mypy src
+      - run: pytest

pytypehintstore-0.0.4/.github/workflows/publish.yml

@@ -0,0 +1,24 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.11"
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv pip install --system -e ".[dev]"
+      - run: mypy src
+      - run: pytest
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

pytypehintstore-0.0.4/.gitignore

@@ -0,0 +1,19 @@
+__pycache__/
+*.py[cod]
+build/
+dist/
+*.egg-info/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.vscode/
+.idea/
+
+# What the example leaves behind: its directory, the store and the copies it
+# rotates, plus a part file from a dump that never landed.
+data/
+*.json.lock
+*.json.part
+tasks.json
+tasks.*.json

pytypehintstore-0.0.4/CHANGELOG.md

@@ -0,0 +1,93 @@
+# Changelog
+
+## [0.0.4]
+
+One library on both platforms: the lock now holds the same contract on POSIX
+that it held on Windows, and the checker agrees on both.
+
+- The lock is settled by the operating system on POSIX too. It was an open
+  handle on Windows — a file Windows will not unlink while it is open — and a
+  bare `O_EXCL` everywhere else, which POSIX does not defend: two processes
+  reaching for one orphaned lockfile could both unlink it and both create their
+  own, ending as two live owners of one file. POSIX now takes an advisory
+  `flock`, which the kernel drops when a process dies, and checks the inode
+  afterwards in case the file was replaced between the open and the lock.
+- An orphan needs no stealing on POSIX: what makes it an orphan is that its
+  `flock` died with its owner. The behaviour a caller sees is unchanged — one
+  owner, orphans reclaimed, the same message naming the live PID.
+- `release` unlinks before closing on POSIX and after closing on Windows, each
+  being the order that cannot hand a second owner the lock.
+- `mypy` passes on both platforms. The Windows probe is declared under
+  `sys.platform` rather than `os.name`, which is the form a checker reads as a
+  platform guard, so `ctypes.WinDLL` is not looked for on Linux.
+- CI runs the suite on `ubuntu-latest` and `windows-latest`, over 3.11, 3.12
+  and 3.13. Half of the lock only exists on one of them.
+- New test: two processes reaching for one orphan at the same instant leave a
+  single owner. It is the property both halves exist to hold, and it runs on
+  both.
+- One difference is left, and declared: with a lockfile nobody is holding, POSIX
+  trusts the `flock` and takes it over — so a recycled pid cannot lock a path
+  out there — while Windows trusts the pid written in it and refuses. Two live
+  stores behave identically on both.
+
+## [0.0.2]
+
+Out of a stress campaign: 1150 generated schemas, four adversarial fronts, and
+the suite from 200 tests to 1583.
+
+- Fixed, data loss: `fingerprint` walked a schema as a tree when it is a graph —
+  the core compiles a class once and shares it between every field naming it —
+  so a class the core compiled in a millisecond could take minutes to
+  fingerprint, and `store_of` hung with no error and no output. Each dataclass
+  is now written once and referred back to. Schemas with the same class in two
+  fields change their fingerprint, and so their file name.
+- Fixed, data loss: a lone surrogate was accepted by `add`, could never be
+  written to a UTF-8 file, and froze every later dump — the failure surfacing
+  only at `close()`, as an error from another library. Such a row is refused at
+  `add` with `SchemaValueError: cannot be written as UTF-8`, after the core has
+  had its say.
+- Fixed, data loss: a union whose options share a transport name — an enum class
+  called `date` beside `date` itself — routed values to the wrong branch, and a
+  stored member came back as a plain string. The store now refuses the schema at
+  open, naming the field and the shared name, before the lockfile is taken. Real
+  collisions only: the same enum with nothing to collide with still works.
+- A `$type`/`$value` wrapper is those two keys and nothing else. A key beside
+  them, or a `$value` that is itself a wrapper, travels intact for the core to
+  refuse instead of being read anyway and erased by the next dump.
+- The format version is checked by type as well as by value, so a `1.0` or a
+  `true` in `v` is no longer read as version 1.
+- Packaging: classifiers, keywords and project URLs for PyPI.
+
+## [0.0.1]
+
+First release. Rows of one `pytypehint`-validated dataclass, kept in memory and
+mirrored to a JSON file a person can open and edit.
+
+- `store_of(cls, directory, *, debounce=2.0, keep=5)` opens the store of one
+  dataclass on a file named for the class and the fingerprint of its schema.
+  Reads answer from memory; writes mutate the dict at once and a writer thread
+  dumps the whole state `debounce` seconds after the burst of writes stops.
+- `add` and `put` accept a row by making the round trip it will make anyway:
+  the instance is encoded to its transport form and rebuilt through the schema,
+  so what the store holds always came out of the constructor and always
+  survives the file. Validation failures are the core's own `SchemaTypeError`
+  and `SchemaValueError`, untouched; the store adds no second validation
+  system.
+- The file carries the transport form — ISO text for a date or a time, the
+  member name for an enum, an object for a nested dataclass — so it stays
+  readable and editable. A row that cannot be read back names the file, the row
+  and the core's error.
+- Dumps are atomic: `.part`, `fsync`, `os.replace`. A dump that fails leaves
+  nothing of itself behind, keeps the state unwritten and is retried; the
+  writer thread never dies of it. The previous file is rotated aside with a
+  nanosecond stamp and copies beyond `keep` are pruned.
+- `close()` dumps what is pending, stops the writer and releases the lock. It is
+  idempotent, and a failure on the way down reaches every caller that was
+  closing the same store. An `atexit` hook closes a store the caller forgot, on
+  a normal interpreter exit.
+- One process owns a store. The lockfile holds the owner's PID and stays open
+  for as long as the lock is held, so a second process is refused at startup
+  rather than corrupting the file later, and two processes racing for the same
+  orphaned lock cannot both end up owning it.
+- Three exceptions, all subclasses of `StoreError`: `StoreLockedError`,
+  `StoreLoadError`, and `StoreError` itself for an operation on a closed store.

pytypehintstore-0.0.4/CIERRE.md

@@ -0,0 +1,275 @@
+# Cierre de 0.0.2
+
+Temporal, para revisión humana. No forma parte del repo publicable.
+
+```
+$ python -m pytest -q
+1583 passed, 13 xfailed in 29.44s
+
+$ python -m mypy            # src
+Success: no issues found in 6 source files
+$ python -m mypy tests
+Success: no issues found in 14 source files
+```
+
+| | 0.0.1 | 0.0.2 |
+|---|---:|---:|
+| tests | 200 | **1583** (+13 xfail) |
+| tiempo de suite en frío | 6,9 s | **29,4 s** (presupuesto 60 s) |
+| líneas de `src/` | 861 | **928** |
+| módulos | 5 | 6 |
+
+---
+
+## Fase 1 — el arreglo del enum, completo
+
+### `src/pytypehintstore/store.py`
+
+Importa `List` y `Struct`, ya públicos y ya usados por el codec:
+
+```diff
+-from pytypehint import SchemaTypeError, SchemaValueError, struct_of
++from pytypehint import List, SchemaTypeError, SchemaValueError, Struct, struct_of
+```
+
+La guarda corre en `__init__`, después de derivar el nombre del archivo (para
+poder citarlo) y **antes** de `folder.mkdir` y de `acquire`:
+
+```diff
+         self._path = folder / name
+         self._name = str(Path(directory) / name)
++        self._ambiguous()
+         self._debounce = float(debounce)
+```
+
+El método, junto a `_open`:
+
+```python
+# Two options of one union that answer to the same transport name are
+# indistinguishable in the file: the wrapper names an option and the reader
+# takes the first that answers. The core allows the pair — an enum class
+# called `date` competes with `date` itself, in different namespaces to it —
+# so the store refuses at the door rather than routing a value to the wrong
+# branch and handing back something nobody stored.
+def _ambiguous(self) -> None:
+    found = _shared_name((self._schema,), (), set())
+
+    if found is None:
+        return
+
+    path, shared = found
+    where = ": ".join(path)
+    raise StoreError(
+        f"{self._name}: {where}: two options of a union share the transport "
+        f"name {shared!r}: rename one of the classes")
+```
+
+Y el recorrido, a nivel de módulo (18 líneas):
+
+```python
+# The first pair of options sharing a transport name, as (path, name), or None.
+# `seen` keeps a recursive schema from being walked forever.
+def _shared_name(shapes, path, seen):
+    names = set()
+
+    for shape in shapes:
+        # A Struct carries its $type inside the object and never competes for
+        # the wrapper's, so a dataclass and an enum may share one name — the
+        # core allows exactly that, and the codec keeps them apart.
+        if type(shape) is Struct:
+            continue
+
+        name = shape.option_id()
+
+        if name in names:
+            return path, name
+
+        names.add(name)
+
+    for shape in shapes:
+        if type(shape) is Struct:
+            if id(shape) in seen:
+                continue
+
+            seen.add(id(shape))
+
+            for field in shape.fields:
+                found = _shared_name(field.shape, (*path, field.name), seen)
+
+                if found is not None:
+                    return found
+
+        elif type(shape) is List:
+            found = _shared_name(shape.item, path, seen)
+
+            if found is not None:
+                return found
+
+    return None
+```
+
+**La exclusión de `Struct` no estaba en el prompt y es necesaria.** Sin ella la
+guarda se pasaba de estricta y rompía un test verde de la suite anterior
+(`test_codec.py::test_an_enum_sharing_its_name_with_a_dataclass_survives_as_a_member`):
+un dataclass y un enum homónimos **funcionan correctamente**, porque un `Struct`
+lleva su `$type` dentro del objeto y nunca compite por el del wrapper — es
+exactamente lo que arregló la auditoría anterior. La guarda mira solo a las
+opciones que pueden viajar envueltas.
+
+Cero privados del core: `option_id()`, `fields`, `field.shape` y `List.item` son
+públicos, y `tests/test_boundary.py` sigue en verde sobre los seis módulos.
+
+### Comportamiento, verificado a mano
+
+| caso | resultado |
+|---|---|
+| `date \| EnumNamedDate` | `RECHAZA — when: two options of a union share the transport name 'date': rename one of the classes` |
+| el mismo enum **sin** `date` al lado | **ABRE**, y guarda sus miembros |
+| anidado a 3 niveles | `RECHAZA — outer: inner: when: …` (el path completo) |
+| dentro de `list[...]` | `RECHAZA — items: …` |
+| dos enums homónimos | lo rechaza **el core** al compilar (`duplicate discriminator name(s)`) |
+| uniones normales (`str\|date`, `list[str]\|list[int]`, `Enum\|None`) | **ABREN** |
+
+---
+
+## Estado final de los 19 xfail
+
+**Seis eran del enum: ninguno queda.** Convertidos en tests del rechazo:
+
+| antes (xfail) | ahora |
+|---|---|
+| `unions::test_an_enum_named_str_keeps_its_member_through_the_store` | `test_an_enum_sharing_a_transport_name_with_a_scalar_is_refused_at_open` — mensaje completo por igualdad |
+| `unions::test_a_date_survives_an_enum_named_date_with_an_iso_member` | `test_a_date_beside_an_enum_named_date_is_refused_either_way_round[enum first]` |
+| `unions::test_an_enum_member_named_like_an_iso_date_survives_a_date_option` | el mismo, `[date first]` |
+| `generated::test_enum_named_like_a_scalar_loses_the_member` (codec puro) | `test_an_enum_named_like_a_scalar_is_why_the_store_checks_the_names` — **adaptado, no borrado**: pinta las dos mitades, lo que el codec haría y el rechazo que lo impide, así que quitar la guarda deja un test diciendo qué vuelve en su lugar |
+| `generated::test_enum_named_like_a_scalar_corrupts_a_stored_row` | `test_a_schema_the_codec_could_not_name_never_becomes_a_store` |
+| `generated::test_enum_named_like_date_loses_the_member` | `test_an_enum_named_like_date_is_refused_the_same_way` |
+
+Además, dos tests que **pasaban** documentando la mitad superviviente de la
+colisión (`test_an_enum_named_str_takes_a_plain_string_with_it`,
+`test_the_same_collision_refuses_other_values_out_loud`) dejaron de tener
+sentido —el store ya no abre ese schema— y se sustituyeron por
+`test_a_refused_schema_leaves_nothing_behind` y
+`test_an_enum_named_like_a_scalar_it_never_meets_is_fine` (el caso negativo).
+
+**Los 13 restantes son todos el mismo límite declarado**, el de la unión de
+listas enrutada por el tipo de los items, ahora con una línea apuntando al
+README en su `reason`:
+
+| test | qué fija |
+|---|---|
+| `generated::test_codec_round_trip[seed14, 48, 230, 374]` | los 4 de 500 schemas generados que lo tocan |
+| `generated::test_the_transport_names_the_branch_the_core_would_choose[seed14, 48, 230, 374]` | el `$type` escrito no es la rama que `value_branch` elegiría |
+| `generated::test_store_round_trip[seed14, 48]` | los mismos, a través de un store real |
+| `generated::test_a_union_of_lists_routes_by_type_alone_on_length` | el caso mínimo: `[]` bajo `Annotated[list[str], Min(1)] \| list[int]` |
+| `…_on_a_pattern` | lo mismo con `Pattern` |
+| `…_on_choices` | lo mismo con `Choices` |
+
+Ninguno quedó obsoleto por la fase 1: son un defecto distinto, en otra capa.
+
+---
+
+## Fase 2 — limpieza
+
+- **Presupuesto: 29,4 s en frío**, menos de la mitad de los 60 s. Ningún test
+  necesitó `@pytest.mark.slow`, así que no se registró el marcador y el README
+  no necesita instrucciones aparte. Los cinco más lentos: 2,1 s (4 hilos contra
+  el escritor), 1,4 s (bisección del techo de recursión), 1,3 s (5000 filas),
+  1,0 s (cobertura del generador), 1,0 s (medición del ritmo de reintento).
+- **Código muerto: no había.** Un barrido AST sobre los 14 archivos de test
+  buscando funciones y clases definidas y nunca usadas no encontró ninguna.
+- **mypy limpio en tests**, además de en src. Cinco avisos, todos por
+  construcciones deliberadas: tres `Enum("date", …)` guardados en variables con
+  otro nombre (es el bug que se está probando), un `v: str | ShadowStr` con una
+  variable como tipo, y una anotación que faltaba en `_LIST_VALUES`. Los cuatro
+  primeros llevan `# type: ignore` con el código exacto; el quinto se anotó.
+  `warn_unused_ignores` está activo, así que si el motivo desaparece, avisa.
+
+---
+
+## Fase 4 — empaquetado
+
+```
+$ python -m build
+Successfully built pytypehintstore-0.0.2.tar.gz and
+                  pytypehintstore-0.0.2-py3-none-any.whl
+
+$ unzip -l dist/pytypehintstore-0.0.2-py3-none-any.whl
+  pytypehintstore/__init__.py  codec.py  errors.py  fingerprint.py
+  lockfile.py  store.py  py.typed
+  pytypehintstore-0.0.2.dist-info/{METADATA,RECORD,WHEEL,licenses/LICENSE}
+```
+
+**El quick start del README, tal cual, contra el wheel en un venv limpio:**
+
+```
+$ .venv/Scripts/pip install dist/pytypehintstore-0.0.2-py3-none-any.whl
+pytypehint 0.0.7 · pytypehintstore 0.0.2
+
+$ .venv/Scripts/python quickstart.py
+path.name: Task.a50534e4.json          ← el mismo nombre que documenta el README
+get: Task(title='Buy milk', priority=<Priority.HIGH: 'high'>, done=False)
+all: [(2, Task(title='Write the store', priority=<Priority.LOW: 'low'>, done=True))]
+reopened: ids kept, next add gave 3
+py.typed viaja: True
+```
+
+`example.py` contra ese mismo wheel, tres ejecuciones seguidas: ids 1‑2, 3‑4,
+5‑6, las filas anteriores intactas y las copias rotadas de su familia. El
+directorio acabó con las **dos** bases de datos conviviendo — la `Task` del quick
+start (`a50534e4`) y la `Task` del ejemplo (`975cbdd0`), dos clases con el mismo
+nombre y distinto contrato — que es el contrato hecho visible.
+
+---
+
+## Decisiones que tomé sin cobertura del prompt
+
+1. **La exclusión de `Struct` en la guarda** (arriba). Sin ella, sobre‑rechazo.
+2. **La dependencia se fija en `pytypehint>=0.0.7`**, la versión actual y contra
+   la que está probado todo. No bisecté qué versión anterior bastaría: habría
+   exigido instalar y correr la suite contra cada una, y el core es del mismo
+   autor y avanza junto.
+3. **Las URLs del `pyproject` asumen `github.com/offerrall/pytypehintstore`**,
+   por el patrón del resto del ecosistema. **Confírmalas antes de publicar**: si
+   el repo se llama de otro modo, son tres líneas.
+4. **La entrada 0.0.1 del CHANGELOG llevaba dos frases falsas** —la firma vieja
+   `store_of(cls, path, …)` y el remedio de `missing key(s)`, ambos retirados en
+   el rediseño— y las corregí en vez de dejarlas: esa versión nunca se publicó,
+   así que su entrada describe la librería, no un histórico.
+5. **`mypy` sigue configurado con `files = ["src"]`**. Los tests pasan si se le
+   pide explícitamente (`mypy tests`), pero no los añadí a la configuración: lo
+   que se publica es el paquete, y el CI ya corre `mypy src`.
+6. **El test del codec puro del enum se adaptó en vez de eliminarse.** El prompt
+   dejaba elegir; conservarlo documenta por qué existe la guarda, y falla con un
+   mensaje útil si alguien la quita.
+
+---
+
+## Lo que queda fuera, a sabiendas
+
+- **El límite de la unión de listas** sigue abierto. Arreglarlo necesita el
+  router de valores del core, que es privado; la alternativa sería reimplementar
+  las restricciones en el codec, es decir, el segundo validador que el diseño
+  no quiere. Está en el README, en 13 xfail estrictos y en `INFORME.md`.
+- ~~**POSIX.** La carrera de los dos dueños del lockfile está cerrada en Windows
+  porque un archivo abierto no se puede borrar; en POSIX sí.~~ **Cerrado en
+  0.0.4**: POSIX toma un `flock` que el kernel suelta al morir el proceso, más
+  una comprobación de inodo. La suite corre ahora en `ubuntu-latest` y
+  `windows-latest`. Queda una diferencia declarada, con test por plataforma: un
+  lockfile que nadie sostiene lo toma POSIX (el `flock` es la evidencia) y lo
+  respeta Windows (el PID lo es).
+- **El traceback compartido del segundo `close()`** (cosmético, ya declarado).
+- **`INFORME.md`** se queda en el repo con el detalle de la campaña; dime si
+  prefieres que se vaya con este `CIERRE.md`.
+
+---
+
+## Veredicto
+
+La propiedad se sostiene con una excepción, y la excepción es ruidosa: **si el
+core compila el schema, el store lo persiste sin pérdida o falla a gritos** — en
+`add`, o en `store_of` antes de tocar el disco. El único caso de corrupción
+silenciosa que la campaña encontró está cerrado, y lo que queda es un rechazo
+molesto y raro (4 de 500 schemas), no una pérdida.
+
+Queda listo para `twine upload`. Ese botón es tuyo.