damn

Author: AWeirdDev

.github/workflows/docs.yml

@@ -0,0 +1,28 @@
+name: ci 
+on:
+  push:
+    branches:
+      - main
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache 
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material 
+      - run: mkdocs gh-deploy --force

docs/dumping.md

@@ -0,0 +1,52 @@
+# Dumping
+
+Dump the model to a data format. Supports nested items.
+
+## JSON
+
+Everyone's favorite data type.
+
+```python
+from exacting import Exact
+
+class Money(Exact):
+    swag: bool
+
+money = Money(swag=True)
+
+json = money.exact_as_json()
+print(json)  # {"swag": true}
+
+data = Money.exact_from_json(json)
+print(data)  # Money(swag=True)
+```
+
+Side note, you can actually load from JSON with comments (jsonc). Just disable strict mode via `strict=False`.
+
+```python
+json = """{
+    "swag": /* false */ true, // yeah, trailing commas
+}"""
+
+data = Money.exact_from_json(json, strict=False)
+print(data)  # Money(swag=True)
+```
+
+
+## Bytes
+
+Exacting uses [rkyv](https://docs.rs/rkyv/latest/rkyv/) for serialization/deserialization.
+
+```python
+from exacting import Exact
+
+class Place(Exact):
+    name: str
+
+place = Place(name="Freddy Fazbear's Pizza")
+archive = place.exact_as_bytes()
+print(archive)  # b"\x00\x00\x00\x00name\xff..."
+
+data = Place.exact_from_bytes(archive)
+print(data)  # Place(name="Freddy Fazbear's Pizza")
+```

docs/fields.md

@@ -0,0 +1,81 @@
+# Fields
+
+Fields in `exacting` are rather pretty straightforward, just as what you'd expect from `dataclasses`.
+
+```python
+from exacting import Exact, field
+
+class StoreItem(Exact):
+    name: str = field()
+    price: int = field()
+```
+
+## Min, max
+
+You can check for the minimum/maximum length or value by passing the `minv` or `maxv` parameter.
+
+```python
+from exacting import Exact, field
+
+class Sequence(Exact):
+    id: str = field(minv=2)  # checks for len()
+    some: int = field(maxv=4)  # checks for value
+    data: list[int] = field(minv=4, maxv=4)  # len() must be 4
+
+
+# ✅ OK!
+Sequence(
+    id="hello",
+    some=4,
+    data=[1, 2, 3, 4]
+)
+```
+
+## Regex
+
+`exacting` also has a built-in Regex matching field utility.
+
+```python
+from exacting import Exact, field
+
+class Hamburger(Exact):
+    name: str = field(regex="^[A-Z]+$")
+
+# ✅ GOOD. Emphasized enough!
+Hamburger(name="WHOPPER")
+
+# ❌ ERROR. Can you be louder?
+Hamburger(name="bigmac")
+```
+
+
+??? failure "TypeError: Error while validating…"
+
+    ```
+    TypeError: 
+    Error while validating dataclass 'Hamburger' at attribute 'name' (field validator):
+    Failed to validate Regex on str (doesn't match)
+    ```
+
+Note that the `regex` parameter won't work (skipped) if used on field types that aren't `str`.
+
+## Aliases
+
+Aliases are only used when serializing/deserializing.
+
+```python
+from exacting import Exact, field
+
+class Person(Exact):
+    name: str
+    description: str = field(alias="desc")
+
+# serializing
+person = Person(name="Me", description="broke af")
+data = person.exact_as_json()
+print(data)  # {"name": "Me", "desc": "broke af"}
+
+# deserializing
+person2 = Person.exact_from_json(data)
+print(person2)  # Person(name='Me', description='broke af')
+```

docs/index.md

@@ -1,17 +1,106 @@
-# Welcome to MkDocs
+# Exacting
 
-For full documentation visit [mkdocs.org](https://www.mkdocs.org).
+> *(adj.) making great demands on one's skill, attention, or other resources.*
 
-## Commands
+`exacting` is a picky dataclass runtime utility collection, making sure all type annotations are followed.
 
-* `mkdocs new [dir-name]` - Create a new project.
-* `mkdocs serve` - Start the live-reloading docs server.
-* `mkdocs build` - Build the documentation site.
-* `mkdocs -h` - Print help message and exit.
+Essentially... **THE** go-to option for dataclasses. heh.
 
-## Project layout
+**🔑 Key features**:
+
+- **100% static typing.** Because I hate nothing too.
+- Up to **10x faster** than [`pydantic`](https://pydantic.dev)! (Them: 60ms, us: 6~9ms)
+
+![static typing](static-typing-proof.png)
+
+<br />
+
+**🛍️ Get `exacting`**:
+
+=== "pip"
+
+    ``` haskell
+    pip install -U exacting
+    ```
+
+=== "uv"
+
+    ``` haskell
+    uv pip install -U exacting
+    ```
+
+=== "git"
+
+    ``` shell
+    git clone https://github.com/AWeirdDev/exacting
+    ```
+
+**🔥 Define some model**:
+
+=== "Python 3.10+"
+
+    ```python
+    from exacting import Exact
+
+    class Actor(Exact):
+        name: str
+        portrays: str
+
+    class Show(Exact):
+        name: str
+        description: str | None
+        actors: list[Actor]
+    ```
+
+=== "Python <= 3.9"
+
+    ```python
+    from typing import List, Optional
+    from exacting import Exact
+
+    class Actor(Exact):
+        name: str
+        portrays: str
+
+    class Show(Exact):
+        name: str
+        description: Optional[str]
+        actors: List[Actor]
+    ```
+
+**📦 Build 'em**:
+
+```python
+# (1) ✅ OK, exacting is happi
+Show(
+    name="Severance",
+    description="great show",
+    actors=[
+        Actor(name="Adam Scott", portrays="Mark S."),
+        Actor(name="Britt Lower", portrays="Helly R."),
+    ]
+)
+
+# (2) ❌ Nuh-uh, exacting is angri
+Show(
+    name=123,
+    description=False,
+    actors=[
+        "Walter White",
+        "Jesse Pinkman"
+    ]
+)
+```
+
+??? failure "TypeError: Error while validating…"
+
+    ``` python
+    TypeError: 
+    Error while validating dataclass 'Show' at attribute 'name':
+    (isinstance) Expected <class 'str'>, got: <class 'int'>
+    ```
+
+Normally, when you use the parameters passed in example (2) above, the Python `dataclasses` library might as well just go with it, because they only put the additional **static typing** to the model, but not at **runtime**. Exacting makes sure that at both times, types are all enforced. It even gives you a detailed error message on where this occurs! (In a cool way)
+
+It's worth noting that error generations are *lazy*, which means once Exacting finds out about a problem, it immediately raises a `TypeError` or `ValueError` (depending on the context) when we're at the high-level scale (say, a dataclass). This saves a lot of computation time if you have a larger model.
 
-    mkdocs.yml    # The configuration file.
-    docs/
-        index.md  # The documentation homepage.
-        ...       # Other markdown pages, images and other files.

docs/static-typing-proof.png

@@ -0,0 +1,14 @@
+# Annotated
+
+Annotated types allow you to annotate any value onto the type field.
+
+```python
+from typing import Annotated
+
+#         type, metadata.......
+Annotated[str,  "any data", 123]
+```
+
+`exacting` only checks for the type, not the metadata.
+
+For future development of `exacting`, it might be used as a doc field.

docs/type-reference/annotated.md

@@ -0,0 +1,10 @@
+# Any
+
+The `Any` type allows any type to be on the surface, which is generally not a good practice in production.
+
+```python
+from typing import Any
+
+Any
+```
+

docs/type-reference/any.md

@@ -0,0 +1,13 @@
+# Literal
+
+Literal types tell `exacting` to check for value equality instead of types.
+
+```python
+from typing import Literal
+
+Literal["Hello", b"beep", 123, True]
+```
+
+There can be multiple `Literal` items.
+
+Literal types perform exactly as intended in `exacting`.

docs/type-reference/literal.md

@@ -0,0 +1,16 @@
+# Native types
+
+Most native types are instantly available! These are all the available types:
+
+```python
+str
+int
+float
+bool
+bytes
+list[...]
+dict[..., ...]
+```
+
+You probably noticed that `tuple` or `set` isn't available. Yes, currently.
+

docs/type-reference/native.md

@@ -0,0 +1,19 @@
+# Union
+
+The union type allows you to have multiple choices of types.
+
+=== "Python 3.10+"
+
+    ```python
+    A | B | C
+    ```
+
+=== "Python <= 3.9"
+
+    ```python
+    from typing import Union
+
+    Union[A, B, C]
+    ```
+
+Union types perform exactly as intended in `exacting`.