Metadata-Version: 2.4
Name: DefPixel
Version: 0.1.2
Summary: A Python toolkit for data connections, modling, and access
Home-page: https://github.com/yong5eon/DefPixel
Author: Heo Yongseon
Project-URL: Source, https://github.com/yong5eon/DefPixel
Project-URL: Issues, https://github.com/yong5eon/DefPixel/issues
Project-URL: Releases, https://github.com/yong5eon/DefPixel/releases
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: postgresql
Requires-Dist: psycopg[binary,pool]<4,>=3.3; extra == "postgresql"
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-python
Dynamic: summary

# DefPixel

Define your data connections, models, and access in Python.

**Define your pixels.**<br>
**Shape your voxels.**

DefPixel is a Python library for defining data source connections, models, and access. Use a provided data access implementation or build your own, and work with data directly or through standard dataclasses.

## Connect · model · use

- Define connections: storage-specific configuration and data access capabilities.
- Define models: storage specifications and validation rules attached to standard dataclasses.
- Use your data: direct access without models, or storage and retrieval through models.

Configuration and Connection provide connection foundations. Database, KeyValue, Document, and Index Protocols describe capabilities. Modeling approaches and support vary by implementation. Validators also provide independent value validation and conversion.

## Requirements and installation

Python 3.10+ is required.

### Sqlite

The Sqlite implementation is included in the base installation and uses Python's standard-library `sqlite3`. Model-based usage requires Sqlite 3.35+ as used by Python.

```shell
pip install DefPixel
```

### PostgreSQL

Install the `PostgreSQL` extra to include the PostgreSQL driver. A running PostgreSQL 15–18 server is required. This installation also includes the Sqlite implementation.

```shell
pip install "DefPixel[PostgreSQL]"
```

## Usage at a glance

### Database

#### Sqlite 

Execute SQL directly for dictionary results or map standard dataclasses to tables and retrieve objects. This complete example requires Sqlite 3.35+ as used by Python.

```python
from dataclasses import dataclass
from DefPixel.DataAccessObject.Implements.Sqlite import (
  Configuration, Connection, column, table,
)
from DefPixel.DataAccessObject.Implements.Sqlite.Constraints import PrimaryKey
from DefPixel.DataAccessObject.Implements.Sqlite.Executors import Create, Insert, Select
from DefPixel.DataAccessObject.Implements.Sqlite.Types import Integer, Text


@table(name='users', constraints=(PrimaryKey('id'),))
@dataclass
class User:
  id: int = column(Integer())
  name: str = column(Text())


connection = Connection(Configuration(':memory:'))
connection.connect()
try:
  with connection.session() as session:
    session.run(Create(User))
    session.run(Insert(User).values(id=1, name='Alice'))

    rows = session.execute(
      'SELECT id, name FROM users WHERE id = ?', 1,
    ).rows()
    print(rows)

    users = session.run(Select(User), fetch=User)
    print(users)
finally:
  connection.close()
```

Output:

```text
[{'id': 1, 'name': 'Alice'}]
[User(id=1, name='Alice')]
```

Sessions commit on normal completion and roll back on exceptions. Direct SQL does not require models. Models remain ordinary Python objects; attribute assignment does not automatically persist changes. No custom Model base class or Service/Repository/DTO structure is required.

#### PostgreSQL

PostgreSQL also supports direct SQL alongside dataclass mappings. Install the PostgreSQL extra above and adjust the connection settings for your server. Run this example in a development database: it creates and drops the `defpixel_readme_users` table.

```python
from dataclasses import dataclass
from DefPixel.DataAccessObject.Implements.PostgreSQL import (
  Configuration, Connection, Create, Drop, Insert, PrimaryKey, Select, column, table,
)
from DefPixel.DataAccessObject.Implements.PostgreSQL.Types import Integer, Text


@table('defpixel_readme_users', constraints=PrimaryKey('defpixel_readme_users_pk', 'id'))
@dataclass
class User:
  id: int = column(Integer())
  name: str = column(Text())


connection = Connection(Configuration(
  host='127.0.0.1', port=5432, database='defpixel',
  username='defpixel', password='change-me-local-only',
))
connection.connect()
try:
  with connection.session() as session:
    session.run(Create(User))
    session.run(Insert(User).values(id=1, name='Alice'))

    rows = session.execute(
      'SELECT id, name FROM defpixel_readme_users WHERE id = %s', 1,
    ).rows()
    print(rows)

    users = session.run(Select(User), fetch=User)
    print(users)
    session.run(Drop(User))
finally:
  connection.close()
```

Output:

```text
[{'id': 1, 'name': 'Alice'}]
[User(id=1, name='Alice')]
```

Direct SQL binds positional arguments with `%s` and keyword arguments with `%(name)s`. PostgreSQL constraints take a name as their first argument.

## Supported implementations

- Sqlite: direct SQL, dataclass mappings, CRUD, tables, views, constraints, indexes, joins, aggregates, and transactions. Sqlite modeling requires Sqlite 3.35+.
- PostgreSQL: direct SQL, dataclass mappings, CRUD, schemas, sequences, tables, views, constraints, indexes, joins, aggregate/window/JSON functions, nested transactions, and connection pools. Requires PostgreSQL 15–18 and the `PostgreSQL` extra.

## Build your own

Implement the capability Protocols for the store you need, without inheriting a provided implementation or adapting every store to SQL.

The source repository includes step-by-step implementation development guides and Sqlite and PostgreSQL user manuals.
