chore: add dev extra, fix docs links, expose __version__, improve CI

.github/workflows/ci.yml

@@ -25,7 +25,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ['3.10', '3.11', '3.12']
+        python-version: ['3.10', '3.11', '3.12', '3.13']
 
     steps:
       - name: Checkout
@@ -39,8 +39,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -e . || pip install .
-          pip install --upgrade ruff black isort pytest pytest-mock coverage
+          pip install -e ".[dev]"
 
       - name: Run ruff
         run: |
@@ -55,7 +54,12 @@ jobs:
 
       - name: Run tests with coverage
         run: |
-          coverage run -m pytest -q
+          if [ "${{ github.event.inputs.run_integration || 'false' }}" = "true" ]; then
+            echo "Running with integration tests enabled (live FTP)"
+            RUN_INTEGRATION=true coverage run -m pytest -q
+          else
+            coverage run -m pytest -q
+          fi
           coverage xml -o coverage.xml
           coverage report -m --fail-under=55
 
@@ -80,7 +84,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: '3.11'
+          python-version: '3.12'
 
       - name: Install formatters and linters
         run: |

CONTRIBUTING.md

@@ -19,7 +19,7 @@ git checkout -b feat/your-feature
 python -m venv .venv
 . ./.venv/bin/activate
 pip install -U pip
-pip install -e .[dev]
+pip install -e ".[dev]"
 ```
 
 Style & linters
@@ -31,7 +31,7 @@ Style & linters
 Run all checks locally before opening a PR:
 
 ```bash
-ruff .
+ruff check .
 isort --check-only .
 black --check .
 ```

README.md

@@ -36,15 +36,15 @@ Quick links
 
 ## Installation
 
-Install in editable mode during development:
+Install in editable mode during development (includes dev/lint/test tools via the `dev` extra):
 
 ```bash
 git clone https://github.com/OncoAtlas/susflow.git
 cd susflow
 python -m venv .venv
 . ./.venv/bin/activate
 pip install -U pip
-pip install -e .
+pip install -e ".[dev]"
 ```
 
 Install from PyPI (recommended for most users):
@@ -99,12 +99,11 @@ By default downloads are stored under `~/.susflow/cache/` mirroring FTP paths. I
 
 ## Developer tools and linters
 
-We recommend the following dev tools for contributors:
+After `pip install -e ".[dev]"` (see Installation above), the tools are available. Run the checks locally:
 
 ```bash
 . ./.venv/bin/activate
-pip install -U ruff black isort pytest pytest-mock coverage
-ruff .
+ruff check .
 black --check .
 isort --check-only .
 pytest -q
@@ -122,7 +121,7 @@ pytest -q
 ## Contributing
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines: coding style, tests, and PR workflow.
-See [docs/contributing/coverage.md](./docs/contributing/coverage.md) for coverage instructions.
+See [docs/en/coverage.md](./docs/en/coverage.md) for coverage instructions.
 
 ## License
 

docs/en/coverage.md

@@ -4,14 +4,13 @@ This file explains how to run the test suite with coverage and generate reports
 
 Commands
 
-1. Create and activate a virtual environment, install the package and test dependencies:
+1. Create and activate a virtual environment, install the package and test dependencies (the `dev` extra brings in coverage, pytest, etc.):
 
 ```bash
 python -m venv .venv
 source .venv/bin/activate
 python -m pip install --upgrade pip
-pip install -e . || pip install .
-pip install coverage pytest pytest-mock
+pip install -e ".[dev]"
 ```
 
 2. Run tests under coverage and show a terminal summary:

docs/pt-br/CONTRIBUTING.md

@@ -18,7 +18,7 @@ git checkout -b feat/sua-funcionalidade
 python -m venv .venv
 . ./.venv/bin/activate
 pip install -U pip
-pip install -e .[dev]
+pip install -e ".[dev]"
 ```
 
 ## Estilo & linters
@@ -30,7 +30,7 @@ pip install -e .[dev]
 Execute todas as verificações localmente antes de abrir um PR:
 
 ```bash
-ruff .
+ruff check .
 isort --check-only .
 black --check .
 ```

docs/pt-br/README.md

@@ -23,15 +23,15 @@ Documentação em inglês: [README principal](../../README.md)
 
 ## Instalação
 
-Instalação em modo editável durante o desenvolvimento:
+Instalação em modo editável durante o desenvolvimento (inclui ferramentas de dev/lint/test via o extra `dev`):
 
 ```bash
 git clone https://github.com/OncoAtlas/susflow.git
 cd susflow
 python -m venv .venv
 . ./.venv/bin/activate
 pip install -U pip
-pip install -e .
+pip install -e ".[dev]"
 ```
 
 Instalação via PyPI (recomendado para a maioria dos usuários):
@@ -88,12 +88,11 @@ Por padrão, os downloads são salvos em `~/.susflow/cache/` espelhando a árvor
 
 ## Ferramentas de desenvolvimento
 
-Recomendamos as seguintes ferramentas para contribuições:
+Após `pip install -e ".[dev]"` (veja Instalação acima), as ferramentas já estão disponíveis. Execute as verificações localmente:
 
 ```bash
 . ./.venv/bin/activate
-pip install -U ruff black isort pytest pytest-mock coverage
-ruff .
+ruff check .
 black --check .
 isort --check-only .
 pytest -q
@@ -110,8 +109,8 @@ pytest -q
 
 ## Contribuindo
 
-Veja [CONTRIBUTING.md](../contributing/CONTRIBUTING.md) para diretrizes de código, testes e fluxo de PR.
-Veja [coverage.md](../contributing/coverage.md) para instruções de cobertura de testes.
+Veja [CONTRIBUTING.md](./CONTRIBUTING.md) para diretrizes de código, testes e fluxo de PR.
+Veja [coverage.md](./coverage.md) para instruções de cobertura de testes.
 
 ## Licença
 

docs/pt-br/coverage.md

@@ -4,14 +4,13 @@ Este arquivo explica como executar a suíte de testes com cobertura e gerar rela
 
 ## Comandos
 
-1. Crie e ative um ambiente virtual, instale o pacote e as dependências de teste:
+1. Crie e ative um ambiente virtual, instale o pacote e as dependências de teste (o extra `dev` inclui coverage, pytest etc.):
 
 ```bash
 python -m venv .venv
 source .venv/bin/activate
 python -m pip install --upgrade pip
-pip install -e . || pip install .
-pip install coverage pytest pytest-mock
+pip install -e ".[dev]"
 ```
 
 2. Execute os testes com cobertura e mostre o resumo no terminal:

pyproject.toml

@@ -19,6 +19,19 @@ dependencies = [
     "dbfread",
 ]
 
+[project.optional-dependencies]
+dev = [
+    "ruff",
+    "black",
+    "isort",
+    "pytest",
+    "pytest-mock",
+    "coverage",
+    # release / packaging helpers
+    "build",
+    "twine",
+]
+
 [project.urls]
 "Homepage" = "https://github.com/OncoAtlas/susflow"
 "PyPI" = "https://pypi.org/project/susflow"

susflow/__init__.py

@@ -1,3 +1,10 @@
+from importlib.metadata import PackageNotFoundError, version
+
 from .ftp import FileNotFoundOnFTPError, FTPError
 from .reader import ReadError, read
 from .systems import cnes, pni, siasus, sihsus, sim, sinan, sinasc
+
+try:
+    __version__ = version("susflow")
+except PackageNotFoundError:
+    __version__ = "0.0.0"  # fallback (e.g. editable without metadata)