Merge pull request #309 from TemoaProject/unstable

setting up ci bots, fixing pytest warnings, improving docs

Author: ParticularlyPythonicBS

.github/ISSUE_TEMPLATE/bug_report.md

@@ -75,7 +75,7 @@ Please provide details about your environment. This helps us reproduce the issue
 *   **Operating System:**
 *   **Python Version:**
 *   **Project Version:**
-*   **Relevant Dependencies:** 
+*   **Relevant Dependencies:**
 
 ## Checklist
 

.github/workflows/ci.yml

@@ -59,8 +59,12 @@ jobs:
       - name: Run tests
         env:
           CI: 1
-        run: uv run pytest tests
+        run: uv run pytest tests --cov --cov-branch --cov-report=xml
 
+      - name: Upload coverage reports to Codecov
+        uses: codecov/codecov-action@75cd11691c0faa626561e295848008c8a7dddffe # v5.3.1
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
   type-check:
     name: type check
     runs-on: ubuntu-latest

.pre-commit-config.yaml

@@ -9,22 +9,22 @@ repos:
         files: ^pyproject\.toml$
 
       # Compile requirements
-      - id: pip-compile
-        name: pip-compile requirements.txt (core dependencies)
+      - id: uv-export
+        name: uv export requirements.txt (core dependencies)
         args:
-          - pyproject.toml # Input file
-          - -o # Output flag
-          - requirements.txt # Output file name
-        files: ^pyproject\.toml$
+          - --no-dev
+          - -o
+          - requirements.txt
+        files: ^(pyproject\.toml|uv\.lock)$
 
-      - id: pip-compile
-        name: pip-compile requirements-dev.txt (core + all optional dependencies)
+      - id: uv-export
+        name: uv export requirements-dev.txt (core + all optional dependencies)
         args:
-          - pyproject.toml
-          - --all-extras # Include all optional dependency groups
+          - --all-extras
+          - --dev
           - -o
-          - requirements-dev.txt # Output file name
-        files: ^pyproject\.toml$
+          - requirements-dev.txt
+        files: ^(pyproject\.toml|uv\.lock)$
 
         # Code quality and formatting
   - repo: https://github.com/pre-commit/pre-commit-hooks

README.md

@@ -2,6 +2,8 @@
 
 [![PyPI](https://img.shields.io/pypi/v/temoa?label=pypi%20package)](https://pypi.org/project/temoa/)
 [![CI](https://github.com/TemoaProject/temoa/actions/workflows/ci.yml/badge.svg?branch=unstable)](https://github.com/TemoaProject/temoa/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/TemoaProject/temoa/graph/badge.svg?token=ZAXU1VM8YN)](https://codecov.io/gh/TemoaProject/temoa)
+[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/TemoaProject/temoa/main.svg)](https://results.pre-commit.ci/latest/github/TemoaProject/temoa/main)
 [![Documentation Status](https://readthedocs.org/projects/temoa/badge/?version=latest)](https://temoa.readthedocs.io/en/latest/?badge=latest)
 [![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue)](https://pyreadiness.org/3.12/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

docs/source/References.bib

@@ -39,4 +39,3 @@ @article{Hunter_etal_2013
 	pages     = "339--349",
 	year      = "2013"
 }
-

docs/source/database.rst

@@ -106,6 +106,81 @@ recommend that you populate input tables in the following order:
   * limit_tech_output_split
 
 
+---------------------------------------
+Group Region and Technology Constraints
+---------------------------------------
+
+Some constraint tables support summation over groups of regions or technologies. Note that each row in these tables will still only create one constraint, but that constraint will be a summation over the defined group. For example, the ``limit_capacity`` table will limit the total summed capacity of all technologies in the technology group (if used) and over all the regions in the region group (if used). Consider behaviour carefully. For example, the ``limit_annual_capacity_factor`` table will constrain the total summed capacity factor of the group, which would allow for varying capacity factors of processes within that group as long as the limit is met in aggregate.
+
+**Group Regions:**
+
+For the supported tables, the ``region`` column can be populated with either a single region (e.g., ``"east"``), a subset of regions delineated with a ``+`` (e.g., ``"east+west"``), or ``"global"`` to indicate summation over all model regions.
+
+.. important::
+   When grouped or global region constraints are used with exchange technologies,
+   exchange flows are only counted if the relevant exchange-technology keys are
+   explicitly included in the region string used by the constraint row.
+   Exchange-technology keys are directional and use a hyphen to separate the
+   two regions (e.g., ``east-west`` and ``west-east`` are distinct keys).
+
+   For example, to constrain activity across the ``east`` and ``west`` regions
+   including all exchange flows between them, the region string should be:
+
+   .. code-block:: none
+
+      east+east-west+west-east+west
+
+   If exchange keys are omitted (e.g., using only ``east+west``), flows through
+   exchange technologies between those regions will *not* be included in the
+   constrained summation.
+
+Supported tables:
+
+* limit_annual_capacity_factor
+* limit_seasonal_capacity_factor
+* limit_resource
+* limit_activity
+* limit_capacity
+* limit_new_capacity
+* limit_activity_share
+* limit_capacity_share
+* limit_new_capacity_share
+* limit_emission
+* limit_growth_capacity
+* limit_growth_new_capacity
+* limit_growth_new_capacity_delta
+* limit_degrowth_capacity
+* limit_degrowth_new_capacity
+* limit_degrowth_new_capacity_delta
+
+**Technology Groups:**
+
+For the supported tables, the following columns accept either technologies or technology groups, over which the constraint is summed. Technology groups are defined in the ``tech_group`` and ``tech_group_member`` tables.
+
+* tech
+* tech_or_group
+* sub_group
+* super_group
+
+Supported tables:
+
+* limit_annual_capacity_factor
+* limit_seasonal_capacity_factor
+* limit_resource
+* limit_activity
+* limit_capacity
+* limit_new_capacity
+* limit_activity_share
+* limit_capacity_share
+* limit_new_capacity_share
+* limit_growth_capacity
+* limit_growth_new_capacity
+* limit_growth_new_capacity_delta
+* limit_degrowth_capacity
+* limit_degrowth_new_capacity
+* limit_degrowth_new_capacity_delta
+
+
 For help getting started, consider using the ``temoa tutorial``
 command to generate a template project or inspect the example SQL file at
 ``temoa/tutorial_assets/utopia.sql``. To begin building your own database file, use

docs/source/default/layout.html

@@ -13,4 +13,3 @@
 {%- endblock %}
 
 {% set script_files = script_files + ['_static/google_analytics.js'] %}
-

docs/source/default/static/google_analytics.js

@@ -7,4 +7,3 @@ _gaq.push(['_trackPageview']);
   ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
   var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
 })();
-

docs/source/default/static/my_theme.css

@@ -14,4 +14,4 @@ max-width: 1200px !important;
     display: inline-block;
     visibility: visible;
     margin-right: -0.7em;
-}
+}