stanwell 0.1.0__tar.gz

stanwell-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v2
+        with:
+          version: "latest"
+
+      - name: Cache uv
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/uv
+          key: ${{ runner.os }}-uv-${{ hashFiles('uv.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-uv-
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Run CI checks
+        run: make ci

stanwell-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,41 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v2
+        with:
+          version: "latest"
+
+      - name: Cache uv
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/uv
+          key: ${{ runner.os }}-uv-${{ hashFiles('uv.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-uv-
+
+      - name: Install dependencies
+        run: uv sync --all-groups
+
+      - name: Build documentation
+        run: make docs-check

stanwell-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,50 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v2
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+
+    environment:
+      name: pypi
+
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v5
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish package
+        uses: pypa/gh-action-pypi-publish@release/v1

stanwell-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+# Stanwell user data
+config.yml
+config.yaml
+*.db
+*.sqlite
+*.sqlite3
+
+# Secrets
+.env
+.env.*
+
+# Python
+__pycache__/
+.venv/
+
+# Sphinx
+docs/_build/
+docs/_latex/
+docs/api/generated
+
+# Testing
+.env.integration
+
+# Pycharm
+.idea/
+
+# Emacs
+*~

stanwell-0.1.0/.readthedocs.yaml

@@ -0,0 +1,16 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

stanwell-0.1.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## [0.1.0] - 2026-11-04
+Initial public release
+
+<!---
+TEMPLATE
+## [Unreleased]
+
+## [0.0.0] - 20XX-XX-XX
+### Added
+- AAA
+### Changed
+- BBB
+### Deprecated
+- CCC
+### Removed
+- DDD
+### Fixed
+- EEE
+### Security
+- FFF
+-->

stanwell-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jan Buermann
+
+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.

stanwell-0.1.0/Makefile

@@ -0,0 +1,31 @@
+.PHONY: test lint format docs docs-clean docs-check tidy ci
+
+test:
+	uv run pytest
+
+lint:
+	uv run ruff check . --fix
+
+format:
+	uv run black src tests
+
+docs:
+	rm -f docs/api/generated/*.rst
+	uv run sphinx-build -M html docs docs/_build
+
+docs-clean:
+	rm -rf docs/api/generated
+	rm -rf docs/_build
+	uv run sphinx-build -M html docs docs/_build
+
+docs-check:
+	uv run sphinx-build -W --keep-going -b html docs docs/_build/html
+
+tidy: lint format
+
+ci:
+	uv run pytest
+	uv run ruff check .
+	uv run mypy -p stanwell
+	uv lock --locked
+	uv run black --check src tests

stanwell-0.1.0/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.5
+Name: stanwell
+Version: 0.1.0
+Summary: Application to helps understand working time and distribution based on Toggl time tracking data.
+Author: Jan Buermann
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: matplotlib>=3.11.2
+Requires-Dist: numpy>=2.5.3
+Requires-Dist: pandas>=3.0.6
+Requires-Dist: python-dateutil>=2.9.0.post0
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: seaborn>=0.13.2
+Requires-Dist: streamlit>=1.64.0
+Requires-Dist: typer>=0.27.2

stanwell-0.1.0/README.md

@@ -0,0 +1,76 @@
+[![CI](https://github.com/jbuerman/stanwell/actions/workflows/ci.yml/badge.svg)](https://github.com/jbuerman/stanwell/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+# Stanwell
+
+*Have enthusiasm. Work sustainably.*
+
+Stanwell analyses working time recorded in Toggl to help you understand how much you work and how that time is distributed across projects, activities and working patterns.
+
+## Quick setup
+
+Initialise Stanwell:
+
+```bash
+stanwell init
+```
+
+Synchronise historical data. Repeat until all missing data has been downloaded:
+
+```bash
+stanwell sync-missing
+```
+
+Refresh recent entries when needed:
+
+```bash
+stanwell refresh-recent
+```
+
+Open the interactive dashboard:
+
+```bash
+stanwell dashboard
+```
+
+## Development
+
+```bash
+uv sync --all-groups
+```
+
+Format and lint the project:
+
+```bash
+uv run make tidy
+```
+
+Run the CI checks locally:
+
+```bash
+uv run make ci
+```
+
+### Documentation
+
+Build the Sphinx documentation:
+
+```bash
+uv run make docs
+```
+
+Open `docs/_build/html/index.html` to view the generated documentation.
+
+### Integration tests
+
+Create an environment file containing an API token and workspace ID using `.env.integration.example` as a template.
+
+Then run:
+
+```bash
+uv run --env-file .env.integration pytest -m integration
+```
+
+## Licence
+
+Stanwell is released under the [MIT Licence](LICENSE).

stanwell-0.1.0/docs/_ext/cli_commands.py

@@ -0,0 +1,64 @@
+"""Generate CLI command documentation from the Typer application."""
+
+from docutils import nodes
+from docutils.parsers.rst import Directive
+
+from stanwell.ui.cli.cli import app
+
+
+class CliCommandsDirective(Directive):
+    """Render registered Typer commands as a definition list."""
+
+    has_content = False
+
+    def run(self) -> list[nodes.Node]:
+        """Build the definition list containing the registered CLI commands."""
+        definition_list = nodes.definition_list()
+
+        for command_info in app.registered_commands:
+            command_name = command_info.name
+            command_help = command_info.help
+            callback = command_info.callback
+
+            if command_name is None or callback is None:
+                continue
+
+            target = (
+                f"{callback.__module__}."
+                f"{callback.__name__}"
+            )
+
+            item = nodes.definition_list_item()
+            term = nodes.term()
+
+            reference_nodes, messages = self.state.inline_text(
+                f":py:func:`{command_name} <{target}>`",
+                self.lineno,
+            )
+            term.extend(reference_nodes)
+
+            definition = nodes.definition()
+            definition += nodes.paragraph(
+                text=command_help or "",
+            )
+
+            item += term
+            item += definition
+            definition_list += item
+
+            definition_list.extend(messages)
+
+        return [definition_list]
+
+
+def setup(app):
+    """Register the CLI command directive."""
+    app.add_directive(
+        "cli-commands",
+        CliCommandsDirective,
+    )
+
+    return {
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

stanwell-0.1.0/docs/api/index.rst

@@ -0,0 +1,11 @@
+API Reference
+=============
+
+This reference documents the public packages, modules, classes and functions
+provided by Stanwell.
+
+.. autosummary::
+   :toctree: generated
+   :recursive:
+
+   stanwell

stanwell-0.1.0/docs/changelog.rst

@@ -0,0 +1,2 @@
+.. include:: ../CHANGELOG.md
+   :parser: myst_parser.sphinx_

stanwell-0.1.0/docs/cli.rst

@@ -0,0 +1,22 @@
+Command-line interface
+======================
+
+The ``stanwell`` command is used to set up Stanwell,
+maintain the local copy of your Toggl data and launch the dashboard.
+
+Commands
+--------
+
+.. cli-commands::
+
+Use the built-in help at any time:
+
+.. code-block:: console
+
+   stanwell --help
+
+Help for an individual command is available in the same way:
+
+.. code-block:: console
+
+   stanwell COMMAND --help

stanwell-0.1.0/docs/conf.py

@@ -0,0 +1,79 @@
+
+import os
+import sys
+import tomllib
+from datetime import date
+from pathlib import Path
+
+DOCS_DIR = Path(__file__).parent
+sys.path.insert(
+    0,
+    str(DOCS_DIR / "_ext"),
+)
+
+PROJECT_ROOT = os.path.abspath(os.path.join(__file__, "..", ".."))
+sys.path.insert(0, os.path.join(PROJECT_ROOT, "src"))
+
+def authors_to_comma_list(pyproject_data, include_emails=False):
+    """Convert PEP 621 authors into a comma-separated string."""
+    authors = pyproject_data.get("project", {}).get("authors", []) or []
+    parts = []
+
+    for a in authors:
+        if isinstance(a, dict):
+            name = (a.get("name") or "").strip()
+            email = (a.get("email") or "").strip()
+            if name or email:
+                if include_emails and name and email:
+                    parts.append(f"{name} <{email}>")
+                elif name:
+                    parts.append(name)
+                elif email:
+                    parts.append(f"<{email}>")
+        elif isinstance(a, str):
+            s = a.strip()
+            if s:
+                parts.append(s)
+    return ", ".join(parts)
+
+with open(os.path.join(PROJECT_ROOT, "pyproject.toml"), "rb") as f:
+    pyproject_data = tomllib.load(f)
+project_version = pyproject_data.get("project", {}).get("version", "-")
+project_name = pyproject_data.get("project", {}).get("name", "-")
+
+project = project_name
+author = authors_to_comma_list(pyproject_data, include_emails=False)
+copyright = f"{date.today().year}, {author}"
+release = project_version
+version = project_version
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.viewcode",
+    "sphinx_paramlinks",
+    "myst_parser",
+    "cli_commands",
+]
+
+autosummary_generate = True
+
+autodoc_typehints = "signature"
+
+autodoc_default_options = {
+    "members": True,
+    "undoc-members": False,
+    "show-inheritance": True,
+}
+
+intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
+templates_path = ["_templates"]
+exclude_patterns = []
+html_static_path = ["_static"]
+
+html_theme = 'sphinx_rtd_theme'
+
+html_logo = "_static/stanwell_logo.png"
+html_favicon = "_static/stanwell_favicon.png"

stanwell-0.1.0/docs/configuration.rst

@@ -0,0 +1,78 @@
+Configuration
+=============
+
+Stanwell uses a YAML configuration file to describe your
+working pattern, local database and Toggl connection.
+
+By default, the command-line interface looks for:
+
+.. code-block:: text
+
+   ~/.config/stanwell/config.yaml
+
+A different configuration file can be selected with the global
+`--config` (or `-c`) option.
+
+Working pattern
+---------------
+
+The configuration describes how the application should interpret your
+recorded time. Important settings include:
+
+`workday_hours`
+    The number of hours in a standard working day.
+
+`working_days`
+    The weekdays on which work is normally required.
+
+`core_start` and `core_end`
+    The normal core-hours interval used when analysing working patterns.
+
+`timezone`
+    The timezone used when interpreting recorded time.
+
+`tracking_start_date`
+    The date from which working-time tracking begins.
+
+For example:
+
+.. code-block:: yaml
+
+   workday_hours: 7.5
+   working_days: [0, 1, 2, 3, 4]
+   timezone: Europe/London
+   core_start: "10:00"
+   core_end: "16:00"
+
+Exception days
+--------------
+
+Exception days represent dates on which the normal working pattern does not
+apply.
+
+The standard exception types are:
+
+`annual_leave`
+    Annual leave.
+
+`sick`
+    Sick leave.
+
+`public_holiday`
+    A public holiday.
+
+`closure_day`
+    An organisation closure day.
+
+`overtime_compensation`
+    Time taken off in lieu of overtime.
+
+Annual leave, sickness, public holidays and closure days remove the normal
+working-time requirement for that day.
+
+Overtime compensation also removes the normal requirement, but differs in
+one important respect: the compensated hours are deducted from the accumulated
+working-time balance.
+
+This allows a day taken in lieu to offset additional time worked previously,
+rather than appearing simply as another non-working day.

stanwell-0.1.0/docs/dashboard.rst

@@ -0,0 +1,55 @@
+Dashboard
+=========
+
+The interactive dashboard turns the locally stored time entries into a set
+of views of your working time.
+
+Open it from the command line:
+
+.. code-block:: console
+
+   stanwell dashboard
+
+The date controls in the dashboard determine the period used for most
+analyses.
+
+Overview
+--------
+
+The Overview brings together the main working-time measures.
+
+It shows recorded and required working time, working-time balance and
+overtime compensation. Daily and weekly views make shorter-term variation
+visible, while the longer-term balance view shows how additional work,
+shortfalls and overtime compensation affect the accumulated balance.
+
+The Overview also provides a weekday view to help identify differences in
+working time across the week.
+
+Projects
+--------
+
+The Projects tab shows how recorded working time is distributed between
+projects.
+
+This is useful for understanding where working time has gone during the
+selected period rather than considering total working hours alone.
+
+Working patterns
+----------------
+
+The Working patterns tab focuses on when work takes place.
+
+It helps make patterns such as work outside core hours and work on
+designated days off visible. These measures complement the simple
+working-time balance: working the expected number of hours does not
+necessarily mean those hours are distributed in a healthy way.
+
+Tag balance
+-----------
+
+The Tag balance tab uses tags attached to Toggl entries to explore categories
+of activity across the selected period.
+
+Tags can overlap, so tagged time should be interpreted as different views of
+the same recorded time rather than necessarily additive categories.