contoso 0.1.0__tar.gz

contoso-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+.hypothesis/
+*.log
+.venv/
+venv/
+ENV/

contoso-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Alejandro Hagan
+
+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.

contoso-0.1.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: contoso
+Version: 0.1.0
+Summary: Synthetic business datasets for the fictional Contoso company
+Project-URL: Homepage, https://codeberg.org/usrbinr/contoso.py
+Project-URL: Repository, https://codeberg.org/usrbinr/contoso.py
+Project-URL: Issues, https://codeberg.org/usrbinr/contoso.py/issues
+Author-email: Alejandro Hagan <alejandro.hagan@outlook.com>
+License: MIT
+License-File: LICENSE
+Keywords: business,contoso,dataset,duckdb,sales
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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: Topic :: Database
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Requires-Dist: duckdb>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# contoso
+
+Synthetic business datasets for the fictional Contoso company. This Python package provides access to 8 interconnected business datasets stored as Parquet files on Cloudflare R2, loaded efficiently via DuckDB.
+
+## Installation
+
+```bash
+pip install contoso
+```
+
+Or install from source:
+
+```bash
+pip install git+https://codeberg.org/usrbinr/contoso.py
+```
+
+## Usage
+
+```python
+import contoso
+
+# Create a DuckDB connection with Contoso datasets
+db = contoso.create_duckdb(size="small")
+
+# Access tables (lazy evaluation via DuckDB relations)
+db["sales"].limit(10).fetchdf()
+db["customer"].filter("Country = 'United States'").fetchdf()
+
+# Available tables
+# - sales: Sales transaction data
+# - product: Product details (name, manufacturer, category)
+# - customer: Customer demographics and geography
+# - store: Store locations and attributes
+# - fx: Foreign exchange rates
+# - calendar: Date dimension table
+# - orders: Order header information
+# - orderrows: Order line items
+
+# Launch interactive web UI
+contoso.launch_ui(db["con"])
+
+# Close connection when done
+db["con"].close()
+```
+
+## Dataset Sizes
+
+| Size   | Sales Rows   |
+|--------|--------------|
+| small  | ~8,000       |
+| medium | ~2.3 million |
+| large  | ~47 million  |
+| mega   | ~237 million |
+
+## Requirements
+
+- Python >= 3.9
+- DuckDB >= 1.0.0
+
+## License
+
+MIT

contoso-0.1.0/README.md

@@ -0,0 +1,62 @@
+# contoso
+
+Synthetic business datasets for the fictional Contoso company. This Python package provides access to 8 interconnected business datasets stored as Parquet files on Cloudflare R2, loaded efficiently via DuckDB.
+
+## Installation
+
+```bash
+pip install contoso
+```
+
+Or install from source:
+
+```bash
+pip install git+https://codeberg.org/usrbinr/contoso.py
+```
+
+## Usage
+
+```python
+import contoso
+
+# Create a DuckDB connection with Contoso datasets
+db = contoso.create_duckdb(size="small")
+
+# Access tables (lazy evaluation via DuckDB relations)
+db["sales"].limit(10).fetchdf()
+db["customer"].filter("Country = 'United States'").fetchdf()
+
+# Available tables
+# - sales: Sales transaction data
+# - product: Product details (name, manufacturer, category)
+# - customer: Customer demographics and geography
+# - store: Store locations and attributes
+# - fx: Foreign exchange rates
+# - calendar: Date dimension table
+# - orders: Order header information
+# - orderrows: Order line items
+
+# Launch interactive web UI
+contoso.launch_ui(db["con"])
+
+# Close connection when done
+db["con"].close()
+```
+
+## Dataset Sizes
+
+| Size   | Sales Rows   |
+|--------|--------------|
+| small  | ~8,000       |
+| medium | ~2.3 million |
+| large  | ~47 million  |
+| mega   | ~237 million |
+
+## Requirements
+
+- Python >= 3.9
+- DuckDB >= 1.0.0
+
+## License
+
+MIT

contoso-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "contoso"
+version = "0.1.0"
+description = "Synthetic business datasets for the fictional Contoso company"
+readme = "README.md"
+license = {text = "MIT"}
+license-files = ["LICENSE"]
+authors = [
+    { name = "Alejandro Hagan", email = "alejandro.hagan@outlook.com" }
+]
+requires-python = ">=3.9"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Database",
+    "Topic :: Scientific/Engineering",
+]
+keywords = ["contoso", "duckdb", "dataset", "sales", "business"]
+dependencies = [
+    "duckdb>=1.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+]
+
+[project.urls]
+Homepage = "https://codeberg.org/usrbinr/contoso.py"
+Repository = "https://codeberg.org/usrbinr/contoso.py"
+Issues = "https://codeberg.org/usrbinr/contoso.py/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/contoso"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]

contoso-0.1.0/src/contoso/__init__.py

@@ -0,0 +1,11 @@
+"""
+Contoso: Synthetic business datasets for the fictional Contoso company.
+
+This package provides access to 8 interconnected business datasets stored
+as Parquet files on Cloudflare R2, loaded efficiently via DuckDB.
+"""
+
+from contoso.database import create_duckdb, launch_ui
+
+__version__ = "0.1.0"
+__all__ = ["create_duckdb", "launch_ui"]

contoso-0.1.0/src/contoso/database.py

@@ -0,0 +1,117 @@
+"""
+Database functions for creating and interacting with Contoso DuckDB databases.
+"""
+
+from typing import Literal
+
+import duckdb
+
+# Cloudflare R2 public bucket URL
+R2_BASE_URL = "https://pub-6aa63519a4b945948cb8c88949b320ca.r2.dev"
+
+# Size to folder mapping
+SIZE_TO_FOLDER = {
+    "small": "contoso_100k",
+    "medium": "contoso_1m",
+    "large": "contoso_10m",
+    "mega": "contoso_100m",
+}
+
+# Table names
+TABLES = ["sales", "product", "customer", "store", "orders", "orderrows", "fx", "calendar"]
+
+
+def create_duckdb(
+    size: Literal["small", "medium", "large", "mega"] = "small"
+) -> dict:
+    """
+    Create a DuckDB connection with Contoso datasets loaded from cloud storage.
+
+    The datasets are stored as Parquet files on Cloudflare R2 and streamed
+    directly into DuckDB as views.
+
+    Parameters
+    ----------
+    size : {"small", "medium", "large", "mega"}, default "small"
+        Dataset size to load:
+        - small: ~8,000 sales rows
+        - medium: ~2.3 million rows
+        - large: ~47 million rows
+        - mega: ~237 million rows
+
+    Returns
+    -------
+    dict
+        A dictionary containing:
+        - 'sales', 'product', 'customer', 'store', 'fx', 'calendar',
+          'orders', 'orderrows': DuckDB Relation objects (lazy evaluation)
+        - 'con': The DuckDB connection object
+
+    Examples
+    --------
+    >>> import contoso
+    >>> db = contoso.create_duckdb(size="small")
+    >>> db["sales"].limit(5).fetchdf()
+    >>> db["con"].close()
+    """
+    size = size.lower()
+    if size not in SIZE_TO_FOLDER:
+        raise ValueError(
+            f"Invalid size '{size}'. Must be one of: {', '.join(SIZE_TO_FOLDER.keys())}"
+        )
+
+    folder = SIZE_TO_FOLDER[size]
+
+    # Create DuckDB connection
+    con = duckdb.connect()
+
+    # Install and load httpfs extension
+    con.execute("INSTALL httpfs; LOAD httpfs;")
+
+    # Create views for each table pointing to R2 parquet files
+    for table in TABLES:
+        parquet_url = f"{R2_BASE_URL}/{folder}/{table}.parquet"
+        con.execute(f"CREATE VIEW {table} AS SELECT * FROM read_parquet('{parquet_url}');")
+
+    # Build result dictionary with lazy relations
+    result = {table: con.table(table) for table in TABLES}
+    result["con"] = con
+
+    return result
+
+
+def launch_ui(con: duckdb.DuckDBPyConnection) -> None:
+    """
+    Launch the DuckDB UI in your browser.
+
+    Installs and launches the DuckDB UI extension for an active DuckDB
+    database connection, allowing interactive exploration via a web interface.
+
+    Parameters
+    ----------
+    con : duckdb.DuckDBPyConnection
+        A valid DuckDB connection object (e.g., from create_duckdb()["con"])
+
+    Returns
+    -------
+    None
+        The function is called for its side effects (launches browser).
+
+    Raises
+    ------
+    ValueError
+        If the connection is None or invalid.
+
+    Examples
+    --------
+    >>> import contoso
+    >>> db = contoso.create_duckdb()
+    >>> contoso.launch_ui(db["con"])
+    >>> db["con"].close()
+    """
+    if con is None:
+        raise ValueError("Database connection is None. Please provide a valid connection.")
+
+    # Install and start the UI extension
+    con.execute("INSTALL ui;")
+    con.execute("CALL start_ui();")

contoso-0.1.0/tests/test_database.py

@@ -0,0 +1,58 @@
+"""Tests for contoso database functions."""
+
+import pytest
+
+import contoso
+
+
+class TestCreateDuckdb:
+    """Tests for create_duckdb function."""
+
+    def test_creates_all_expected_tables(self):
+        """Test that create_duckdb creates all expected tables."""
+        db = contoso.create_duckdb(size="small")
+
+        expected_keys = [
+            "sales", "product", "customer", "store", "fx",
+            "calendar", "orders", "orderrows", "con"
+        ]
+
+        assert set(db.keys()) == set(expected_keys)
+
+        # Clean up
+        db["con"].close()
+
+    def test_tables_are_queryable(self):
+        """Test that created tables can be queried."""
+        db = contoso.create_duckdb(size="small")
+
+        # Each table should be queryable
+        for table_name in ["sales", "product", "customer", "store", "fx", "calendar", "orders", "orderrows"]:
+            result = db[table_name].limit(1).fetchall()
+            assert result is not None
+
+        db["con"].close()
+
+    def test_invalid_size_raises_error(self):
+        """Test that invalid size raises ValueError."""
+        with pytest.raises(ValueError, match="Invalid size"):
+            contoso.create_duckdb(size="invalid")
+
+    def test_size_case_insensitive(self):
+        """Test that size parameter is case insensitive."""
+        db = contoso.create_duckdb(size="SMALL")
+        assert "con" in db
+        db["con"].close()
+
+        db = contoso.create_duckdb(size="Small")
+        assert "con" in db
+        db["con"].close()
+
+
+class TestLaunchUi:
+    """Tests for launch_ui function."""
+
+    def test_none_connection_raises_error(self):
+        """Test that None connection raises ValueError."""
+        with pytest.raises(ValueError, match="connection is None"):
+            contoso.launch_ui(None)