ga-gataframe 0.1.0__tar.gz

ga_gataframe-0.1.0/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## 0.1.0 - 2026-09-02
+
+- Prepared the package for the future `andreagemma/gataframe` GitHub repository.
+- Moved the import package to `src/gataframe`.
+- Added project metadata, CI/release workflows, documentation, tests, and MIT
+  license information for GataFrame.
+- Fixed valid `GataFrame` column operations that were rejected by overly broad
+  assertion checks.
+- Removed the serializer helper from the public package and documentation.
+

ga_gataframe-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrea Gemma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ga_gataframe-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include LICENSE
+include CHANGELOG.md
+include README.md
+recursive-include docs *.md
+recursive-include src/gataframe py.typed

ga_gataframe-0.1.0/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.4
+Name: ga-gataframe
+Version: 0.1.0
+Summary: DuckDB-backed dataframe helpers for tabular and geospatial data workflows.
+Author: Andrea Gemma
+License-Expression: MIT
+Project-URL: Documentation, https://github.com/andreagemma/gataframe#readme
+Project-URL: Issues, https://github.com/andreagemma/gataframe/issues
+Project-URL: Source, https://github.com/andreagemma/gataframe
+Keywords: gataframe,duckdb,dataframe,pandas,geopandas,etl
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+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
+Classifier: Topic :: Database :: Front-Ends
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: duckdb>=1.1
+Requires-Dist: geopandas>=0.14
+Requires-Dist: pandas>=2.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-cov>=5.0; extra == "test"
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: joblib>=1.4; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: twine>=5.1; extra == "dev"
+Provides-Extra: parallel
+Requires-Dist: joblib>=1.4; extra == "parallel"
+Dynamic: license-file
+
+# GataFrame
+
+[![CI](https://github.com/andreagemma/gataframe/actions/workflows/ci.yml/badge.svg)](https://github.com/andreagemma/gataframe/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/ga-gataframe.svg)](https://pypi.org/project/ga-gataframe/)
+[![Python](https://img.shields.io/pypi/pyversions/ga-gataframe.svg)](https://pypi.org/project/ga-gataframe/)
+
+GataFrame is a lightweight Python library built around DuckDB relations. It
+adds a dataframe-style wrapper plus file and database read-write helpers for
+tabular and geospatial workflows.
+
+The PyPI distribution is named `ga-gataframe`; the import package is named
+`gataframe`.
+
+## Installation
+
+```bash
+python -m pip install ga-gataframe
+```
+
+Development and test tools are available as extras:
+
+```bash
+python -m pip install -e ".[test]"
+python -m pip install -e ".[dev]"
+```
+
+Optional parallel cleanup helpers are available with:
+
+```bash
+python -m pip install -e ".[parallel]"
+```
+
+## Quick Start
+
+```python
+import pandas as pd
+
+from gataframe import connect
+
+engine = connect(extensions=None)
+
+gf = engine.read(pd.DataFrame({"id": [1, 2], "value": [10, 20]}))
+result = gf.withColumn("double_value", "value * 2").filter("double_value > 20").toPandas()
+
+assert result["double_value"].tolist() == [40]
+
+engine.close()
+```
+
+## GataFrame
+
+`GataFrame` wraps a `duckdb.DuckDBPyRelation` and keeps operations chainable.
+Most methods return a new `GataFrame` unless `inplace=True` is passed.
+
+```python
+import pandas as pd
+
+from gataframe import connect
+
+engine = connect(extensions=None)
+gf = engine.read(pd.DataFrame({"a": [1, 2], "b": [3, 4]}))
+
+out = (
+    gf.withColumn("total", "a + b")
+    .renameColumn("total", "sum_ab")
+    .replaceColumn("sum_ab", "sum_ab * 10")
+    .select("a", "sum_ab")
+)
+
+assert out.columns == ["a", "sum_ab"]
+```
+
+Common methods include:
+
+- `withColumn(name, expression)` and `replaceColumn(name, expression)`
+- `renameColumn(old, new)` and `excludeColumn(*columns)`
+- `select(*columns)`, `filter(expression)`, and `limit(n)`
+- `createTable(...)`, `createView(...)`, `dropTable(...)`, and `dropView(...)`
+- `toPandas()`, `toGeoPandas(...)`, and `toPandasOrGeoPandas(...)`
+
+## Engine
+
+`Engine` owns the DuckDB connection and handles input/output.
+
+```python
+from gataframe import connect
+
+engine = connect(extensions=None, file_based=False)
+
+gf = engine.read("data.csv", header=True)
+engine.write(gf, "out.parquet", mode="overwrite")
+
+engine.close()
+```
+
+Supported readers and writers are inferred from file extensions where possible:
+CSV, JSON, Parquet, GeoParquet, GeoJSON, GeoPackage, Shapefile, SQLite, and
+PostgreSQL connection URLs.
+
+DuckDB extensions are loaded only when requested by the caller or needed by a
+specific geospatial/database operation.
+
+## API Summary
+
+- `connect(logger=None, extensions=None, options=None, file_based=False, file=None)`
+- `read(engine, source, format=None, pre_limit=None, limit=None, ...)`
+- `write(engine, df, destination, mode="overwrite", partitionBy=None, ...)`
+- `Engine.connect(...)`
+- `Engine.read(source, format=None, ...)`
+- `Engine.write(df, destination, mode="overwrite", ...)`
+- `GataFrame.withColumn(...)`, `replaceColumn(...)`, `renameColumn(...)`
+- `GataFrame.select(...)`, `filter(...)`, `limit(...)`, `union(...)`
+- `GataFrame.toPandas()`, `toGeoPandas(...)`, and `toPandasOrGeoPandas(...)`
+
+## Development
+
+GataFrame supports Python 3.10 and newer.
+
+```bash
+python -m pip install -e ".[dev]"
+python -m compileall -q src
+python -m pytest --cov=gataframe --cov-report=term-missing
+ruff format --check .
+ruff check .
+mypy
+python -m pip check
+python -m build
+python -m twine check dist/*
+```
+
+## GitHub Repository Setup
+
+This project is prepared for the future repository `andreagemma/gataframe`.
+
+1. Create the empty repository on GitHub.
+2. Initialize the local repository if needed and push the project to `main`.
+3. Confirm the CI workflow passes on GitHub.
+4. Configure the PyPI Trusted Publisher for project `ga-gataframe`, owner
+   `andreagemma`, repository `gataframe`, workflow `release.yml`, and
+   environment `pypi`.
+
+## Releases
+
+`src/gataframe/_version.py` is the only version source. To publish a release:
+
+1. Update `__version__` in `_version.py` and commit the release changes.
+2. Push `main` and wait for CI to pass.
+3. Run the **Create release** GitHub Actions workflow. With no override it
+   creates the `v<version>` tag, creates release notes, and dispatches the build
+   and PyPI publication workflow.
+
+PyPI versions are immutable. Increment `_version.py` before publishing different
+content.
+
+## License
+
+GataFrame is distributed under the MIT License. See [LICENSE](LICENSE).

ga_gataframe-0.1.0/README.md

@@ -0,0 +1,157 @@
+# GataFrame
+
+[![CI](https://github.com/andreagemma/gataframe/actions/workflows/ci.yml/badge.svg)](https://github.com/andreagemma/gataframe/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/ga-gataframe.svg)](https://pypi.org/project/ga-gataframe/)
+[![Python](https://img.shields.io/pypi/pyversions/ga-gataframe.svg)](https://pypi.org/project/ga-gataframe/)
+
+GataFrame is a lightweight Python library built around DuckDB relations. It
+adds a dataframe-style wrapper plus file and database read-write helpers for
+tabular and geospatial workflows.
+
+The PyPI distribution is named `ga-gataframe`; the import package is named
+`gataframe`.
+
+## Installation
+
+```bash
+python -m pip install ga-gataframe
+```
+
+Development and test tools are available as extras:
+
+```bash
+python -m pip install -e ".[test]"
+python -m pip install -e ".[dev]"
+```
+
+Optional parallel cleanup helpers are available with:
+
+```bash
+python -m pip install -e ".[parallel]"
+```
+
+## Quick Start
+
+```python
+import pandas as pd
+
+from gataframe import connect
+
+engine = connect(extensions=None)
+
+gf = engine.read(pd.DataFrame({"id": [1, 2], "value": [10, 20]}))
+result = gf.withColumn("double_value", "value * 2").filter("double_value > 20").toPandas()
+
+assert result["double_value"].tolist() == [40]
+
+engine.close()
+```
+
+## GataFrame
+
+`GataFrame` wraps a `duckdb.DuckDBPyRelation` and keeps operations chainable.
+Most methods return a new `GataFrame` unless `inplace=True` is passed.
+
+```python
+import pandas as pd
+
+from gataframe import connect
+
+engine = connect(extensions=None)
+gf = engine.read(pd.DataFrame({"a": [1, 2], "b": [3, 4]}))
+
+out = (
+    gf.withColumn("total", "a + b")
+    .renameColumn("total", "sum_ab")
+    .replaceColumn("sum_ab", "sum_ab * 10")
+    .select("a", "sum_ab")
+)
+
+assert out.columns == ["a", "sum_ab"]
+```
+
+Common methods include:
+
+- `withColumn(name, expression)` and `replaceColumn(name, expression)`
+- `renameColumn(old, new)` and `excludeColumn(*columns)`
+- `select(*columns)`, `filter(expression)`, and `limit(n)`
+- `createTable(...)`, `createView(...)`, `dropTable(...)`, and `dropView(...)`
+- `toPandas()`, `toGeoPandas(...)`, and `toPandasOrGeoPandas(...)`
+
+## Engine
+
+`Engine` owns the DuckDB connection and handles input/output.
+
+```python
+from gataframe import connect
+
+engine = connect(extensions=None, file_based=False)
+
+gf = engine.read("data.csv", header=True)
+engine.write(gf, "out.parquet", mode="overwrite")
+
+engine.close()
+```
+
+Supported readers and writers are inferred from file extensions where possible:
+CSV, JSON, Parquet, GeoParquet, GeoJSON, GeoPackage, Shapefile, SQLite, and
+PostgreSQL connection URLs.
+
+DuckDB extensions are loaded only when requested by the caller or needed by a
+specific geospatial/database operation.
+
+## API Summary
+
+- `connect(logger=None, extensions=None, options=None, file_based=False, file=None)`
+- `read(engine, source, format=None, pre_limit=None, limit=None, ...)`
+- `write(engine, df, destination, mode="overwrite", partitionBy=None, ...)`
+- `Engine.connect(...)`
+- `Engine.read(source, format=None, ...)`
+- `Engine.write(df, destination, mode="overwrite", ...)`
+- `GataFrame.withColumn(...)`, `replaceColumn(...)`, `renameColumn(...)`
+- `GataFrame.select(...)`, `filter(...)`, `limit(...)`, `union(...)`
+- `GataFrame.toPandas()`, `toGeoPandas(...)`, and `toPandasOrGeoPandas(...)`
+
+## Development
+
+GataFrame supports Python 3.10 and newer.
+
+```bash
+python -m pip install -e ".[dev]"
+python -m compileall -q src
+python -m pytest --cov=gataframe --cov-report=term-missing
+ruff format --check .
+ruff check .
+mypy
+python -m pip check
+python -m build
+python -m twine check dist/*
+```
+
+## GitHub Repository Setup
+
+This project is prepared for the future repository `andreagemma/gataframe`.
+
+1. Create the empty repository on GitHub.
+2. Initialize the local repository if needed and push the project to `main`.
+3. Confirm the CI workflow passes on GitHub.
+4. Configure the PyPI Trusted Publisher for project `ga-gataframe`, owner
+   `andreagemma`, repository `gataframe`, workflow `release.yml`, and
+   environment `pypi`.
+
+## Releases
+
+`src/gataframe/_version.py` is the only version source. To publish a release:
+
+1. Update `__version__` in `_version.py` and commit the release changes.
+2. Push `main` and wait for CI to pass.
+3. Run the **Create release** GitHub Actions workflow. With no override it
+   creates the `v<version>` tag, creates release notes, and dispatches the build
+   and PyPI publication workflow.
+
+PyPI versions are immutable. Increment `_version.py` before publishing different
+content.
+
+## License
+
+GataFrame is distributed under the MIT License. See [LICENSE](LICENSE).

ga_gataframe-0.1.0/docs/api.md

@@ -0,0 +1,43 @@
+# API Reference
+
+## `connect`
+
+```python
+connect(logger=None, extensions=None, options=None, file_based=False, file=None)
+```
+
+Creates an `Engine`. The package-level helper defaults to `extensions=None` so
+basic dataframe work does not try to install DuckDB extensions.
+
+## `Engine`
+
+```python
+Engine.connect(...)
+engine.read(source, format=None, pre_limit=None, limit=None, ...)
+engine.write(df, destination, mode="overwrite", ...)
+```
+
+`Engine` owns the DuckDB connection. It reads Pandas dataframes, `GataFrame`
+instances, and supported file/database sources into DuckDB relations, then wraps
+them as `GataFrame`.
+
+Supported file formats include CSV, JSON, Parquet, GeoParquet, GeoJSON,
+GeoPackage, Shapefile, SQLite, and PostgreSQL URLs.
+
+## `GataFrame`
+
+```python
+GataFrame(relation, con=None, alias=None, description=None, version=0)
+```
+
+Wraps a `duckdb.DuckDBPyRelation` and returns chainable `GataFrame` instances.
+
+Main methods:
+
+- `withColumn(name, expression)` and `replaceColumn(name, expression)`
+- `renameColumn(old, new)` and `excludeColumn(*columns)`
+- `select(*columns)`, `filter(expression)`, and `limit(n)`
+- `createTable(...)`, `createView(...)`, `dropTable(...)`, and `dropView(...)`
+- `union(other)`, `sql(sql)`, and `execute(sql)`
+- `as_type(columns)`
+- `toPandas()`, `toGeoPandas(...)`, and `toPandasOrGeoPandas(...)`

ga_gataframe-0.1.0/docs/index.md

@@ -0,0 +1,8 @@
+# GataFrame Documentation
+
+GataFrame wraps DuckDB relations with dataframe-style helpers for tabular,
+geospatial, file, and database workflows.
+
+- See [API Reference](api.md) for the public classes and methods.
+- See the project [README](../README.md) for installation, quick start,
+  development, release, and GitHub setup instructions.

ga_gataframe-0.1.0/pyproject.toml

@@ -0,0 +1,111 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ga-gataframe"
+dynamic = ["version"]
+description = "DuckDB-backed dataframe helpers for tabular and geospatial data workflows."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  { name = "Andrea Gemma" }
+]
+keywords = ["gataframe", "duckdb", "dataframe", "pandas", "geopandas", "etl"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Database :: Front-Ends",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed"
+]
+dependencies = [
+  "duckdb>=1.1",
+  "geopandas>=0.14",
+  "pandas>=2.0",
+  "pydantic>=2.0"
+]
+
+[project.optional-dependencies]
+test = [
+  "pytest>=8.0",
+  "pytest-cov>=5.0"
+]
+dev = [
+  "build>=1.2",
+  "joblib>=1.4",
+  "mypy>=1.10",
+  "pytest>=8.0",
+  "pytest-cov>=5.0",
+  "ruff>=0.5",
+  "twine>=5.1"
+]
+parallel = [
+  "joblib>=1.4"
+]
+
+[project.urls]
+Documentation = "https://github.com/andreagemma/gataframe#readme"
+Issues = "https://github.com/andreagemma/gataframe/issues"
+Source = "https://github.com/andreagemma/gataframe"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+gataframe = ["py.typed"]
+
+[tool.setuptools.dynamic]
+version = {attr = "gataframe._version.__version__"}
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra --strict-markers"
+
+[tool.coverage.run]
+branch = true
+source = ["gataframe"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+exclude = [
+  ".venv",
+  "build",
+  "dist",
+  "src/gataframe.egg-info",
+  "venv",
+  "wheel-smoke-test"
+]
+
+[tool.ruff.lint]
+select = ["E9", "F63", "F7", "F82"]
+
+[tool.mypy]
+python_version = "3.10"
+files = ["src/gataframe"]
+warn_unused_configs = true
+check_untyped_defs = true
+follow_imports = "skip"
+no_site_packages = true
+ignore_missing_imports = true
+disable_error_code = ["import-untyped"]
+
+[[tool.mypy.overrides]]
+module = [
+  "gataframe.engine",
+  "gataframe.files",
+  "gataframe.gata_frame"
+]
+ignore_errors = true

ga_gataframe-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+