Merge pull request #69 from pralab/68-release-management

Version management

.github/workflows/docs.yml

@@ -21,10 +21,10 @@ jobs:
 
     steps:
     - uses: actions/checkout@v4
-    - name: Set up Python
-      uses: actions/setup-python@v5
+    - name: Set up Python 3.10
+      uses: actions/setup-python@v4
       with:
-        python-version: "3"
+        python-version: '3.10'
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip

.github/workflows/readthedocs-pr.yaml

@@ -11,6 +11,8 @@ jobs:
   documentation-links:
     runs-on: ubuntu-latest
     steps:
+      - name: Checkout
+        uses: actions/checkout@v4
       - uses: readthedocs/actions/preview@v1
         with:
           project-slug: "secml-torch"

.github/workflows/release.yml

@@ -2,7 +2,10 @@ name: CI
 
 on:
   push:
-    branches: main
+    branches:
+      main
+    paths:
+      - 'VERSION'
 
 jobs:
   build:

.readthedocs.yaml

@@ -16,9 +16,9 @@ sphinx:
   configuration: docs/source/conf.py
 
 # Optionally build your docs in additional formats such as PDF and ePub
-# formats:
-#    - pdf
-#    - epub
+formats:
+   - pdf
+  #  - epub
 
 # Optional but recommended, declare the Python requirements required
 # to build your documentation

VERSION

@@ -0,0 +1 @@
+1.0.0

docs/requirements.txt

@@ -2,3 +2,5 @@ sphinx
 sphinx_rtd_theme
 numpydoc
 myst-parser
+sphinx-autodoc-typehints
+sphinx-copybutton

docs/source/conf.py

@@ -6,22 +6,59 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
+import os
+import pathlib
+import sys
+
+sys.path.insert(0, os.path.abspath("../../src"))
+
+
 project = "SecML-Torch"
 copyright = "2024, Maura Pintor, Luca Demetrio"
 author = "Maura Pintor, Luca Demetrio"
-release = "v0.1"
+
+
+version_path = pathlib.Path(__file__).parent.parent.parent / "VERSION"
+
+# Get the version file from VERSION file
+with version_path.open() as f:
+    version = f.read()
+release = version
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.doctest",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.todo",
+    "sphinx.ext.coverage",
     "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.autosectionlabel",
+    "sphinx_copybutton",
     "myst_parser",
 ]
 
+autosummary_generate = True
+
+
+# Napoleon settings
 napoleon_google_docstring = False
-napoleon_use_param = False
+napoleon_numpy_docstring = True
+napoleon_include_init_with_doc = True
+napoleon_include_private_with_doc = True
+napoleon_include_special_with_doc = True
+napoleon_use_admonition_for_examples = False
+napoleon_use_admonition_for_notes = False
+napoleon_use_admonition_for_references = False
 napoleon_use_ivar = True
+napoleon_use_param = True
+napoleon_use_rtype = True
+
+autodoc_mock_imports = ["foolbox", "torch", "tensorboard"]
 
 templates_path = ["_templates"]
 exclude_patterns = ["*tests*"]

ruff.toml

@@ -24,6 +24,7 @@ ignore = [
     "FBT002",  # boolean type default argument
     "COM812", # flake8-commas "Trailing comma missing"
     "ISC001",  # implicitly concatenated string literals on one line
+    "UP007"
     ]
 
 [lint.per-file-ignores]

setup.py

@@ -2,12 +2,18 @@
 
 from setuptools import find_packages, setup
 
-here = pathlib.Path(__file__).parent.resolve() / "README.md"
+readme = pathlib.Path(__file__).parent.resolve() / "README.md"
+version = pathlib.Path(__file__).parent.resolve() / "VERSION"
 
 # Get the long description from the README file
-with here.open() as f:
+with readme.open() as f:
     long_description = f.read()
 
+# Get the version file from VERSION file
+with version.open() as f:
+    version_nr = f.read()
+
+
 CLASSIFIERS = """\
 Development Status :: 3 - Alpha
 Intended Audience :: Science/Research
@@ -25,9 +31,10 @@
 Topic :: Scientific/Engineering
 """
 
+
 setup(
     name="secml-torch",
-    version="0.1.1",
+    version=version_nr,
     description="SecML-Torch Library",
     classifiers=[_f for _f in CLASSIFIERS.split("\n") if _f],
     long_description=long_description,

src/secmlt/__init__.py

@@ -1 +1,8 @@
 # noqa: D104
+
+import pathlib
+
+version_path = pathlib.Path(__file__).parent.parent.parent / "VERSION"
+
+with version_path.open() as f:
+    __version__ = f.read()

src/secmlt/adv/evasion/aggregators/ensemble.py

@@ -1,6 +1,7 @@
 """Ensemble metrics for getting best results across multiple attacks."""
 
 from abc import ABC, abstractmethod
+from typing import Union
 
 import torch
 from secmlt.adv.evasion.perturbation_models import LpPerturbationModels
@@ -159,7 +160,7 @@ def __init__(
         self,
         loss_fn: torch.nn.Module,
         maximize: bool = True,
-        y_target: torch.Tensor | None = None,
+        y_target: Union[torch.Tensor, None] = None,
     ) -> None:
         """
         Create fixed epsilon ensemble.

src/secmlt/adv/evasion/modular_attack.py

@@ -1,7 +1,7 @@
 """Implementation of modular iterative attacks with customizable components."""
 
 from functools import partial
-from typing import Literal
+from typing import Literal, Union
 
 import torch.nn
 from secmlt.adv.evasion.base_evasion_attack import BaseEvasionAttack
@@ -33,7 +33,7 @@ def __init__(
         y_target: int | None,
         num_steps: int,
         step_size: float,
-        loss_function: str | torch.nn.Module,
+        loss_function: Union[str, torch.nn.Module],
         optimizer_cls: str | partial[Optimizer],
         manipulation_function: Manipulation,
         initializer: Initializer,

src/secmlt/metrics/classification.py

@@ -1,5 +1,7 @@
 """Classification metrics for machine-learning models and for attack performance."""
 
+from typing import Union
+
 import torch
 from secmlt.models.base_model import BaseModel
 from torch.utils.data import DataLoader
@@ -67,7 +69,7 @@ def _compute(self) -> torch.Tensor:
 class AttackSuccessRate(Accuracy):
     """Single attack success rate from attack results."""
 
-    def __init__(self, y_target: float | torch.Tensor | None = None) -> None:
+    def __init__(self, y_target: Union[float, torch.Tensor, None] = None) -> None:
         """
         Create attack success rate metric.
 
@@ -131,7 +133,7 @@ def _accumulate(self, y_pred: torch.Tensor, y_true: torch.Tensor) -> None:
 class EnsembleSuccessRate(AccuracyEnsemble):
     """Worst-case success rate of multiple attack runs."""
 
-    def __init__(self, y_target: float | torch.Tensor | None = None) -> None:
+    def __init__(self, y_target: Union[float, torch.Tensor, None] = None) -> None:
         """
         Create ensemble success rate metric.
 

src/secmlt/trackers/trackers.py

@@ -1,6 +1,7 @@
 """Trackers for attack metrics."""
 
 from abc import ABC, abstractmethod
+from typing import Union
 
 import torch
 from secmlt.adv.evasion.perturbation_models import LpPerturbationModels
@@ -69,7 +70,7 @@ def get(self) -> torch.Tensor:
         """
         return torch.stack(self.tracked, -1)
 
-    def get_last_tracked(self) -> None | torch.Tensor:
+    def get_last_tracked(self) -> Union[None, torch.Tensor]:
         """
         Get last element tracked.
 
@@ -124,7 +125,7 @@ def track(
 class ScoresTracker(Tracker):
     """Tracker for model scores."""
 
-    def __init__(self, y: int | torch.Tensor = None) -> None:
+    def __init__(self, y: Union[int, torch.Tensor] = None) -> None:
         """Create scores tracker."""
         if y is None:
             super().__init__("Scores", MULTI_SCALAR)