triplexanalytics 0.2.2__cp39-abi3-win_amd64.whl

triplex/__init__.py

@@ -0,0 +1,170 @@
+"""Triplex Analytics in plain Python: schema contracts, anonymization and synthetic data.
+
+The engine is the same native code the `triplex` command line runs. Everything happens in this
+process, on this machine; nothing is sent anywhere.
+
+A table goes in as a file path, a pandas or Polars DataFrame, or anything else Arrow can read.
+A result table comes back as a `Table`, which converts to whichever of those you use.
+"""
+
+import io
+import json
+import os
+from dataclasses import dataclass
+
+from . import _native
+from ._native import TriplexError
+
+__all__ = [
+    "Result",
+    "Table",
+    "TriplexError",
+    "anonymize",
+    "convert",
+    "draft_contract",
+    "infer_schema",
+    "synthesize",
+    "validate",
+]
+
+# Rows read from a file to infer its schema, as in the command line. A table passed in memory
+# is always read in full.
+SAMPLE_ROWS = 1000
+
+
+class Table:
+    """A result table, held as Arrow IPC stream bytes until you ask for it in a library's form."""
+
+    def __init__(self, ipc):
+        self.ipc = ipc
+
+    def to_arrow(self):
+        import pyarrow as pa
+
+        return pa.ipc.open_stream(self.ipc).read_all()
+
+    def to_pandas(self):
+        return self.to_arrow().to_pandas()
+
+    def to_polars(self):
+        import polars as pl
+
+        return pl.read_ipc_stream(io.BytesIO(self.ipc))
+
+    def __arrow_c_stream__(self, requested_schema=None):
+        return self.to_arrow().__arrow_c_stream__(requested_schema)
+
+
+@dataclass(frozen=True)
+class Result:
+    """What an anonymize or synthesize run produced: the table and the run's report."""
+
+    table: Table
+    report: dict
+
+
+def _input(data):
+    """`(path, ipc)` for the engine: a path stays a path, a table becomes Arrow IPC bytes."""
+    if isinstance(data, (str, os.PathLike)):
+        return os.fspath(data), None
+    if isinstance(data, Table):
+        return None, data.ipc
+    if hasattr(data, "write_ipc_stream"):  # Polars, which needs no pyarrow for this
+        buffer = io.BytesIO()
+        data.write_ipc_stream(buffer)
+        return None, buffer.getvalue()
+
+    import pyarrow as pa
+
+    if type(data).__module__.partition(".")[0] == "pandas":
+        # The row index is not a column of the dataset.
+        table = pa.Table.from_pandas(data, preserve_index=False)
+    else:
+        table = pa.table(data)
+    sink = pa.BufferOutputStream()
+    with pa.ipc.new_stream(sink, table.schema) as writer:
+        writer.write_table(table)
+    return None, sink.getvalue().to_pybytes()
+
+
+def infer_schema(data, *, sample_rows=SAMPLE_ROWS, delimiter=None):
+    """Infer the schema of `data` and return it as a dict (what `triplex schema` prints).
+
+    `delimiter` is the field separator of a `.csv` path that does not use a comma.
+    """
+    path, ipc = _input(data)
+    return json.loads(_native.infer_schema(path, ipc, sample_rows, delimiter))
+
+
+def draft_contract(data, *, output=None, sample_rows=SAMPLE_ROWS, delimiter=None):
+    """A starting contract for `data`: every column with the type found in it, all required.
+
+    Returns the contract as a dict, which `validate` accepts. `output` also writes it as a
+    `.triplex.yaml` file. A draft only describes the table it was made from: add the limits you
+    expect (null rate, value range, mean, pattern) before you rely on it.
+    """
+    path, ipc = _input(data)
+    contract, yaml = _native.draft_contract(path, ipc, sample_rows, delimiter)
+    if output is not None:
+        with open(output, "w", encoding="utf-8") as file:
+            file.write(yaml)
+    return json.loads(contract)
+
+
+def validate(data, contract, *, sample_rows=SAMPLE_ROWS, delimiter=None):
+    """Check `data` against `contract`: a `.triplex.yaml` path, or a contract as a dict.
+
+    A dict is what `draft_contract` returns, or the same shape built or edited in Python.
+    Returns the validation report: `{"valid": bool, "errors": [...]}`.
+    """
+    if isinstance(contract, dict):
+        if any("inferred_type" in column for column in contract.get("columns", ())):
+            # The two dicts look alike, but an inferred schema describes one table as it is and
+            # sets no expectation to check against.
+            raise TypeError(
+                "this is an inferred schema, not a contract; "
+                "pass triplex.draft_contract(data) to check against the same columns and types"
+            )
+        contract_path, contract_text = None, json.dumps(contract)
+    else:
+        contract_path, contract_text = os.fspath(contract), None
+    path, ipc = _input(data)
+    return json.loads(
+        _native.validate(contract_path, contract_text, path, ipc, sample_rows, delimiter)
+    )
+
+
+def convert(input, output, *, input_delimiter=None, output_delimiter=None):
+    """Convert the file at `input` to the format of `output`'s extension. Returns the report."""
+    return json.loads(_native.convert(input, output, input_delimiter, output_delimiter))
+
+
+def anonymize(
+    data, recipe, *, mapping_out, output=None, mapping_passphrase_env=None, exclude_rows=()
+):
+    """Mask the columns the `.triplex.yaml` recipe at `recipe` declares.
+
+    Each salt is read from the environment variable its recipe column names. The mapping file,
+    which can reverse the result, is written to `mapping_out` and is not returned; name an
+    environment variable in `mapping_passphrase_env` to have it encrypted. `output` also writes
+    the masked table as CSV. `exclude_rows` are 0-based rows to leave out.
+
+    The result is pseudonymized, not anonymous: see `report["warning"]`.
+    """
+    path, ipc = _input(data)
+    table, report = _native.anonymize(
+        recipe, mapping_out, path, ipc, output, mapping_passphrase_env, set(exclude_rows)
+    )
+    return Result(Table(table), json.loads(report))
+
+
+def synthesize(data, *, rows=None, seed=42, min_category_count=5, method="copula", output=None):
+    """Generate a synthetic table shaped like `data`.
+
+    `method` is `"copula"`, `"bayes-net"` or `"marginals"`. None of the three carries a formal
+    privacy guarantee: read `report["privacy_statement"]` and the leakage figures in the report.
+    `rows` defaults to as many as the input has. `output` also writes the table as CSV.
+    """
+    path, ipc = _input(data)
+    table, report = _native.synthesize(path, ipc, output, rows, seed, min_category_count, method)
+    return Result(Table(table), json.loads(report))

triplexanalytics-0.2.2.dist-info/METADATA

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: triplexanalytics
+Version: 0.2.2
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Security
+Requires-Dist: pytest ; extra == 'dev'
+Requires-Dist: pyarrow ; extra == 'dev'
+Requires-Dist: pandas ; extra == 'dev'
+Requires-Dist: polars ; extra == 'dev'
+Provides-Extra: dev
+Summary: Triplex Analytics in plain Python: schema contracts, anonymization and synthetic data, run locally.
+Keywords: privacy,anonymization,pseudonymization,synthetic-data,schema
+License-Expression: Apache-2.0
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Changelog, https://github.com/triplexanalytics/triplex/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://triplexanalytics.io/docs/python.html
+Project-URL: Homepage, https://triplexanalytics.io
+Project-URL: Source, https://github.com/triplexanalytics/triplex
+
+# triplex-python
+
+Triplex Analytics in plain Python: infer and check schema contracts, anonymize a table, generate
+synthetic data. No notebook, no browser, no server. The engine is the same native code the
+`triplex` command line runs.
+
+Not published yet. Install from a source checkout (needs the Rust toolchain):
+
+```sh
+cd packages/triplex-python
+pip install maturin
+maturin develop --release
+```
+
+## Use
+
+```python
+import pandas as pd
+import triplex
+
+# 1. Check the raw export against the contract you keep in version control.
+raw = pd.read_csv("customers.csv")
+report = triplex.validate(raw, "customers.triplex.yaml")
+if not report["valid"]:
+    raise SystemExit(report["errors"])
+
+# 2. Your own pandas work: clean, filter, derive, drop.
+df = raw.dropna(subset=["email"])
+df = df[df["plan"] != "free"]
+df["age_band"] = (df["age"] // 10) * 10
+df = df.drop(columns=["signup_date"])
+
+# 3. See what the table holds now: types, null rates, likely identifiers.
+schema = triplex.infer_schema(df)
+
+# 4. Generate a synthetic copy for tests or a demo.
+run = triplex.synthesize(df, rows=1000, seed=1)
+synthetic = run.table.to_pandas()
+run.report["leakage"]
+```
+
+| Function | What it does |
+|---|---|
+| `infer_schema(data)` | The inferred schema as a dict |
+| `draft_contract(data, output=...)` | A starting contract: every column with its type, all required. Returns a dict; `output` also writes it as `.triplex.yaml` |
+| `validate(data, contract)` | Checks `data` against a contract (a `.triplex.yaml` path or a dict); returns `{"valid": ..., "errors": [...]}` |
+| `convert(input, output)` | Converts a file between `.csv`, `.tsv`, `.jsonl` and `.parquet`, by extension |
+| `anonymize(data, recipe, mapping_out=...)` | Masks the columns a `.triplex.yaml` recipe declares |
+| `synthesize(data, rows=..., seed=..., method=...)` | Generates a synthetic table; `method` is `"copula"` (default), `"bayes-net"` or `"marginals"` |
+
+A contract is what you expect the data to be; an inferred schema is what one table holds right
+now. `draft_contract` gives you a first contract to edit (add null-rate, range, mean or pattern
+limits) and commit. Passing the dict from `infer_schema` to `validate` is an error.
+
+`data` is a file path, a pandas or Polars DataFrame, a pyarrow Table, or anything else Arrow can
+read. `anonymize` and `synthesize` read `.csv` and `.parquet` paths; `infer_schema` and
+`validate` also read `.tsv` and `.jsonl`.
+
+`anonymize` and `synthesize` return a result with two fields: `report` (a dict) and `table`.
+Read the table with `table.to_pandas()`, `table.to_polars()` or `table.to_arrow()`, or pass
+`output="result.csv"` to have it written as CSV as well.
+
+An engine error is raised as `triplex.TriplexError`, with a stable `code` such as
+`"COLUMN_NOT_FOUND"`.
+
+pandas, Polars and pyarrow are optional: install the ones you use. pandas input and
+`to_pandas()` need pyarrow; Polars works without it.
+
+## Anonymizing
+
+```python
+import os
+os.environ["CUSTOMER_SALT"] = "..."   # better: set it outside the script
+
+run = triplex.anonymize(df, "recipe.triplex.yaml", mapping_out="mapping.csv")
+masked = run.table.to_pandas()
+```
+
+- **The salt** is read from the environment variable each recipe column names (`salt_env`). It
+  is never a function argument.
+- **The mapping file** reverses the pseudonyms. It is written to the path you give in
+  `mapping_out` and is not returned to Python. Pass `mapping_passphrase_env="SOME_VAR"` to have
+  it encrypted with the passphrase in that variable.
+- The result is pseudonymized, not anonymous, as long as the mapping file exists. The report says
+  so in `report["warning"]`.
+
+## Synthetic data
+
+None of the three methods here carries a formal privacy guarantee. Every report includes a
+`privacy_statement` and measured leakage figures; read them before sharing the output.
+Identifier-like columns and dates are left out of the synthetic table and listed in
+`report["columns_dropped"]`.
+
+The differentially private methods and the sketch method of the command line are not available
+from Python yet.
+
+## Where your data goes
+
+Nowhere. The engine runs inside your Python process and makes no network call. Files are read
+from and written to the paths you pass.
+
+## Limits
+
+- Column types of a result table are inferred by the engine from the values (integer, float,
+  boolean or text). They are not copied from the input, so a date column comes back as text.
+- A table is copied when it is handed to the engine and again when it comes back. Large tables
+  are untested.
+- Tested on Linux with CPython 3.13, pandas, Polars and pyarrow.
+

triplexanalytics-0.2.2.dist-info/RECORD

@@ -0,0 +1,6 @@
+triplex/__init__.py,sha256=eXEr6t1gvvPmMWUgznPLyO3HrbvVHuUXkDvjyusQ1S0,6528
+triplex/_native.pyd,sha256=5dYccwA7zTgosrZ7foFPymUoC-eXOtnEHL-6ECImZHA,10924032
+triplexanalytics-0.2.2.dist-info/METADATA,sha256=LtL2WwakxvsxFSii-PG9BFmhl7zUSZOhMpo6qNz4LWY,5881
+triplexanalytics-0.2.2.dist-info/WHEEL,sha256=xe4_tbg8wYdeh4O7nLbnWckzIQtCR4nODDgwke_TKy8,95
+triplexanalytics-0.2.2.dist-info/sboms/triplex-python.cyclonedx.json,sha256=gUPBjv7UHBtoi4OS83pwOtVW6bUqmdkwLZ1M1Ai6BgY,139470
+triplexanalytics-0.2.2.dist-info/RECORD,,

triplexanalytics-0.2.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.15.0)
+Root-Is-Purelib: false
+Tag: cp39-abi3-win_amd64