feat: improve ducklake api struture

.github/workflows/python-package.yml

@@ -71,10 +71,10 @@ jobs:
     - uses: actions/checkout@v4
 
     - name: Build Docker image
-      run: docker compose -f docker/docker-compose.yaml build
+      run: docker compose build
 
     - name: Start container
-      run: docker compose -f docker/docker-compose.yaml up -d
+      run: docker compose up -d
 
     - name: Wait for Jupyter
       run: |
@@ -84,8 +84,8 @@ jobs:
         done
 
     - name: Run tests inside container
-      run: docker compose -f docker/docker-compose.yaml exec -T -w /usr/src jupyter python3 -m pytest -vv pysus/tests/ --retries 3 --retry-delay 15 -x -o cache_dir=/tmp/.pytest_cache
+      run: docker compose exec -T -w /usr/src jupyter python3 -m pytest -vv pysus/tests/ --retries 3 --retry-delay 15 -x -o cache_dir=/tmp/.pytest_cache
 
     - name: Cleanup
       if: always()
-      run: docker compose -f docker/docker-compose.yaml down -v
+      run: docker compose down -v

.github/workflows/release.yaml

@@ -91,6 +91,11 @@ jobs:
       with:
         python-version: "3.12"
 
+    - name: Install system dependencies
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y pandoc
+
     - name: Install dependencies
       run: |
         pip install poetry wget

docker/Dockerfile → Dockerfile

@@ -25,12 +25,10 @@ RUN useradd -ms /bin/bash pysus \
 
 COPY pyproject.toml poetry.lock LICENSE README.md /usr/src/
 COPY pysus /usr/src/pysus
-COPY docker/scripts/entrypoint.sh /entrypoint.sh
-COPY docker/notebooks/ /home/pysus/Notebooks/
+COPY entrypoint.sh /entrypoint.sh
 
 RUN pip install poetry \
   && cd /usr/src && poetry config virtualenvs.create false && poetry install --with docs \
-  && pip install 'httpx<0.28' \
   && chown -R pysus:pysus /home/pysus
 
 USER pysus

Makefile

@@ -22,7 +22,7 @@ export PRINT_HELP_PYSCRIPT
 help:
 	@python -c "$$PRINT_HELP_PYSCRIPT" < $(MAKEFILE_LIST)
 
-DOCKER = docker compose -p pysus -f docker/docker-compose.yaml
+DOCKER = docker compose -p pysus
 SERVICE :=
 SEMANTIC_RELEASE = npx --yes \
           -p semantic-release \
@@ -56,7 +56,7 @@ test-pysus: ## run tests quickly with the default Python
 
 .PHONY: test-pysus-with-coverage
 test-pysus-with-coverage: ## run tests with coverage report
-	poetry run pytest -vv pysus/tests/ --retries 3 --retry-delay 15 --cov=pysus --cov-report=xml:coverage.xml --cov-report=term-missing
+	poetry run pytest -vv pysus/tests/ --cov=pysus --cov-report=xml:coverage.xml --cov-report=term-missing
 
 .PHONY: lint
 lint:

README.md

@@ -37,43 +37,54 @@ docker run -p 8888:8888 alertadengue/pysus
 Or build locally and start the container:
 
 ```bash
-docker compose -f docker/docker-compose.yaml up --build
+docker compose up --build
 ```
 
 Then open [http://127.0.0.1:8888/lab](http://127.0.0.1:8888/lab) in your browser.
 
 Stop the container:
 
 ```bash
-docker compose -f docker/docker-compose.yaml down
+docker compose down
 ```
 
 ## Quick Start
 
 ### Simplified Database Functions (New in 2.0)
 
-The easiest way to get data as a pandas DataFrame:
+By default, the high-level convenience functions query and download data locally, returning a list of paths to the downloaded Parquet files. This allows you to inspect the file structure or load them with your preferred tool (e.g., pandas, Polars, DuckDB).
 
 ```python
 from pysus import sinan, sinasc, sim, sih, sia, pni, ibge, cnes, ciha
 
-# Download SINAN Dengue data for 2000
-df = sinan(disease="deng", year=2000)
+# Download SINAN Dengue data for 2000 and return a list of Parquet paths
+parquet_files = sinan(disease="deng", year=2000)
 
 # Multiple years
-df = sinan(disease="deng", year=[2023, 2024])
+parquet_files = sinan(disease="deng", year=[2023, 2024])
 
 # SINASC births for São Paulo, 2020-2023
-df = sinasc(state="SP", year=[2020, 2021, 2022, 2023])
+parquet_files = sinasc(state="SP", year=[2020, 2021, 2022, 2023])
 
 # SIM mortality data
-df = sim(state="SP", year=2024)
+parquet_files = sim(state="SP", year=2024)
 
 # SIH hospitalizations with month
-df = sih(state="SP", year=2024, month=[1, 2, 3])
+parquet_files = sih(state="SP", year=2024, month=[1, 2, 3])
 
 # CNES health facilities
-df = cnes(state="SP", year=2024, month=1)
+parquet_files = cnes(state="SP", year=2024, month=1)
+```
+
+### Loading as a DataFrame Directly
+If you prefer to load and combine the data automatically into a single pandas DataFrame, pass the as_dataframe=True parameter to any of the functions:
+
+```python
+import pandas as pd
+from pysus import sinan
+
+# Download and return a concatenated pandas DataFrame
+df = sinan(disease="deng", year=2024, as_dataframe=True)
 ```
 
 ### Listing the files
@@ -257,7 +268,7 @@ pytest tests/
 Run tests inside the Docker container:
 
 ```bash
-docker compose -f docker/docker-compose.yaml exec -T -w /usr/src jupyter python3 -m pytest pysus/tests/
+docker compose exec -T -w /usr/src jupyter python3 -m pytest pysus/tests/
 ```
 
 ## License

docker/docker-compose.yaml → docker-compose.yaml

@@ -1,8 +1,8 @@
 services:
   jupyter:
     build:
-      context: ".."
-      dockerfile: docker/Dockerfile
+      context: "."
+      dockerfile: Dockerfile
     hostname: pysus-jupyter
     container_name: pysus-jupyter
     ports:

docs/source/conf.py

@@ -21,7 +21,10 @@
 }
 
 templates_path = ["_templates"]
+
+# Explicitly map extensions to ensure notebooks are routed to nbsphinx
 source_suffix = ".rst"
+
 master_doc = "index"
 
 project = "PySUS"