django-periodic-tasks 0.1.0a3__tar.gz

django_periodic_tasks-0.1.0a3/.gitignore

@@ -0,0 +1,224 @@
+# Created by https://www.toptal.com/developers/gitignore/api/python,linux,macos
+# Edit at https://www.toptal.com/developers/gitignore?templates=python,linux,macos
+
+### Linux ###
+*~
+
+# temporary files which can be created if a process still has a handle open of a deleted file
+.fuse_hidden*
+
+# KDE directory preferences
+.directory
+
+# Linux trash folder which might appear on any partition or disk
+.Trash-*
+
+# .nfs files are created when an open file is removed but is still being accessed
+.nfs*
+
+### macOS ###
+# General
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Icon must end with two \r
+Icon
+
+
+# Thumbnails
+._*
+
+# Files that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+### macOS Patch ###
+# iCloud generated files
+*.icloud
+
+### Python ###
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+### Python Patch ###
+# Poetry local configuration file - https://python-poetry.org/docs/configuration/#local-configuration
+poetry.toml
+
+# ruff
+.ruff_cache/
+
+# LSP config files
+pyrightconfig.json
+
+# End of https://www.toptal.com/developers/gitignore/api/python,linux,macos

django_periodic_tasks-0.1.0a3/.gitlab-ci.yml

@@ -0,0 +1,59 @@
+workflow:
+  rules:
+    - if: $CI_COMMIT_REF_PROTECTED == "true"
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+
+stages:
+  - test
+  - docs
+  - release
+
+cache:
+  key: "$CI_PROJECT_NAME"
+  paths:
+    - $HOME/.cache/pip
+
+include:
+  - component: gitlab.com/thelabnyc/thelab-ci-components/review@0.7.1
+  - component: gitlab.com/thelabnyc/thelab-ci-components/precommit@0.7.1
+  - component: gitlab.com/thelabnyc/thelab-ci-components/publish-gitlab-release@0.7.1
+  - component: gitlab.com/thelabnyc/thelab-ci-components/publish-to-pypi@0.7.1
+
+test:
+  stage: test
+  image: "registry.gitlab.com/thelabnyc/python:${IMAGE}"
+  variables:
+    POSTGRES_DB: postgres
+    POSTGRES_USER: postgres
+    POSTGRES_PASSWORD: ""
+    POSTGRES_HOST_AUTH_METHOD: "trust"
+  services:
+    - postgres:latest
+  script:
+    - uv sync --all-extras
+    - uv run tox
+  coverage: '/^TOTAL.+?(\d+\%)$/'
+  parallel:
+    matrix:
+      - IMAGE: "3.13"
+        TOX_SKIP_ENV: "^(?!py313-)"
+      - IMAGE: "3.14"
+        TOX_SKIP_ENV: "^(?!py314-)"
+
+pages:
+  stage: docs
+  image: "registry.gitlab.com/thelabnyc/python:3.14"
+  rules:
+    - if: $CI_COMMIT_REF_PROTECTED == "true"
+  needs:
+    - test
+  variables:
+    DJANGO_SETTINGS_MODULE: sandbox.settings_docgen
+  script:
+    - uv sync --all-extras
+    - uv run mkdocs build --strict
+    - rm -rf ./public
+    - mv ./build/mkdocs ./public
+  artifacts:
+    paths:
+      - public

django_periodic_tasks-0.1.0a3/.pre-commit-config.yaml

@@ -0,0 +1,44 @@
+repos:
+  - repo: https://gitlab.com/thelabnyc/thelab-pre-commit-hooks
+    rev: v0.0.3
+    hooks:
+      - id: update-copyright-year
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-json
+      - id: check-merge-conflict
+      - id: check-symlinks
+      - id: check-toml
+      - id: check-yaml
+        args: [--unsafe]
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+
+  - repo: https://github.com/asottile/pyupgrade
+    rev: v3.21.2
+    hooks:
+      - id: pyupgrade
+        args: [--py313-plus]
+
+  - repo: https://github.com/adamchainz/django-upgrade
+    rev: "1.29.1"
+    hooks:
+    -   id: django-upgrade
+
+  - repo: https://github.com/pycqa/isort
+    rev: "7.0.0"
+    hooks:
+      - id: isort
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.10
+    hooks:
+      - id: ruff
+      - id: ruff-format
+
+  - repo: https://github.com/commitizen-tools/commitizen
+    rev: v4.10.1
+    hooks:
+      - id: commitizen

django_periodic_tasks-0.1.0a3/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## v0.1.0a3 (2026-02-05)
+
+## v0.1.0a2 (2026-02-05)
+
+### Fix
+
+- gitignored uv.lock
+
+## v0.1.0a1 (2026-02-05)
+
+## v0.1.0a0 (2026-02-05)
+
+### Feat
+
+- auto-discover tasks.py modules in installed apps
+- add exactly-once docs, fluentcron examples, remove scheduler_db_worker
+- add bug fixes and exactly-once decorator for scheduled tasks
+- add MkDocs documentation with auto-generated API reference
+- add integration tests
+- add Django admin interface
+- add management commands
+- add PeriodicTaskScheduler with Docker test infrastructure
+- add code-to-DB schedule sync
+- add task path resolver
+- add schedule registry and @scheduled_task decorator
+- add ScheduledTask model
+- add cron expression utilities
+- initial project scaffolding
+
+### Fix
+
+- race condition in scheduler re-queuing
+- uv commands
+- remove dead code around TaskExec SKIPPED status
+- hold row locks for entire tick to prevent duplicate task enqueue
+
+### Refactor
+
+- consolidate mocked tests and remove redundant test cases
+- cleanup imports
+- tweak how scheduler start works

django_periodic_tasks-0.1.0a3/CLAUDE.md

@@ -0,0 +1,50 @@
+# django-periodic-tasks
+
+Periodic/cron task scheduling for django-tasks. Backend-agnostic replacement for celery-beat.
+
+## Project Structure
+
+- `django_periodic_tasks/` - Main package
+  - `models.py` - ScheduledTask model
+  - `registry.py` - ScheduleRegistry, ScheduleEntry, @scheduled_task decorator
+  - `cron.py` - Cron expression utilities (croniter wrapper)
+  - `sync.py` - Code-to-DB sync
+  - `scheduler.py` - PeriodicTaskScheduler (daemon thread)
+  - `task_resolver.py` - Resolve task_path -> Task object
+  - `admin.py` - Django admin (read-only for code-defined tasks)
+  - `management/commands/` - run_scheduler
+- `sandbox/` - Development/test Django project
+- `tests/` - Test suite
+
+## Development
+
+Tests run inside Docker (PostgreSQL required for SELECT FOR UPDATE SKIP LOCKED):
+
+```bash
+mise run test         # Run test suite
+mise run mypy         # Type checking
+mise run coverage     # Tests with coverage
+mise run tox          # Full tox matrix
+```
+
+Or directly with docker compose:
+
+```bash
+docker compose run --rm test uv run python sandbox/manage.py test --noinput -v 2 tests
+```
+
+## Settings
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `PERIODIC_TASKS_AUTOSTART` | `bool` | `False` | Start scheduler daemon thread on `AppConfig.ready()` |
+| `PERIODIC_TASKS_SCHEDULER_INTERVAL` | `int` | `15` | Seconds between scheduler ticks |
+
+## Key Conventions
+
+- Python 3.13+ required
+- All code must pass mypy strict mode
+- Tests use django-tasks DummyBackend with ENQUEUE_ON_COMMIT=False
+- ScheduledTask.save() auto-computes next_run_at when it's None and task is enabled
+- Code-defined schedules use source=CODE, admin-defined use source=DATABASE
+- Scheduler uses SELECT FOR UPDATE SKIP LOCKED for safe multi-worker deployment

django_periodic_tasks-0.1.0a3/Dockerfile

@@ -0,0 +1,8 @@
+FROM registry.gitlab.com/thelabnyc/python:3.14@sha256:1be853e6f27965f57ba0fc6bdc2651ecbc3bcb02becc38b983b6af363cbc39ed
+ENV PYTHONUNBUFFERED 1
+
+RUN mkdir /code
+WORKDIR /code
+
+ADD . /code/
+RUN uv sync

django_periodic_tasks-0.1.0a3/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025, thelab
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

django_periodic_tasks-0.1.0a3/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: django-periodic-tasks
+Version: 0.1.0a3
+Summary: Periodic/cron task scheduling for django-tasks. Backend-agnostic replacement for celery-beat.
+Project-URL: Homepage, https://gitlab.com/thelabnyc/django-periodic-tasks
+Project-URL: Repository, https://gitlab.com/thelabnyc/django-periodic-tasks
+Author-email: thelab <thelabdev@thelab.co>
+License: ISC
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: croniter>=1.0
+Requires-Dist: django-tasks>=0.7
+Requires-Dist: django>=5.2
+Provides-Extra: rq
+Requires-Dist: django-rq; extra == 'rq'
+Requires-Dist: django-tasks[rq]; extra == 'rq'
+Description-Content-Type: text/markdown
+
+# django-periodic-tasks
+
+Periodic/cron task scheduling for [django-tasks](https://github.com/RealOrangeOne/django-tasks). Backend-agnostic replacement for celery-beat + django-celery-beat.
+
+## Installation
+
+```bash
+pip install django-periodic-tasks
+```
+
+Add to `INSTALLED_APPS`:
+
+```python
+INSTALLED_APPS = [
+    ...
+    "django_periodic_tasks",
+]
+```
+
+## Usage
+
+### Define scheduled tasks
+
+```python
+from django_tasks import task
+from django_periodic_tasks import scheduled_task
+
+@scheduled_task(cron="0 5 * * *", name="daily-report")
+@task()
+def daily_report() -> None:
+    ...
+```
+
+### Run the scheduler
+
+Enable the autostart setting so the scheduler runs as a daemon thread inside your Django process:
+
+```python
+# settings.py
+PERIODIC_TASKS_AUTOSTART = True
+```
+
+Or run it as a standalone process:
+
+```bash
+python manage.py run_scheduler
+```

django_periodic_tasks-0.1.0a3/README.md

@@ -0,0 +1,47 @@
+# django-periodic-tasks
+
+Periodic/cron task scheduling for [django-tasks](https://github.com/RealOrangeOne/django-tasks). Backend-agnostic replacement for celery-beat + django-celery-beat.
+
+## Installation
+
+```bash
+pip install django-periodic-tasks
+```
+
+Add to `INSTALLED_APPS`:
+
+```python
+INSTALLED_APPS = [
+    ...
+    "django_periodic_tasks",
+]
+```
+
+## Usage
+
+### Define scheduled tasks
+
+```python
+from django_tasks import task
+from django_periodic_tasks import scheduled_task
+
+@scheduled_task(cron="0 5 * * *", name="daily-report")
+@task()
+def daily_report() -> None:
+    ...
+```
+
+### Run the scheduler
+
+Enable the autostart setting so the scheduler runs as a daemon thread inside your Django process:
+
+```python
+# settings.py
+PERIODIC_TASKS_AUTOSTART = True
+```
+
+Or run it as a standalone process:
+
+```bash
+python manage.py run_scheduler
+```

django_periodic_tasks-0.1.0a3/bin/publish.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+
+set -euxo pipefail
+
+# Check git status
+git fetch --all
+CURRENT_BRANCH=$(git branch --show-current)
+if [ "$CURRENT_BRANCH" != "master" ]; then
+    echo "This script must be run only when the master branch is checked out, but the current branch is ${CURRENT_BRANCH}. Abort!"
+    exit 1
+fi
+
+NUM_BEHIND=$(git log ..origin/master | wc -l | awk '{print $1}')
+if [ "$NUM_BEHIND" == "0" ]; then
+    echo ""
+else
+    echo "Your branch is NOT up to date with origin/master. Abort! Please fetch and rebase first."
+    exit 1
+fi
+
+# Update version and publish via commitizen
+cz bump "$@"

django_periodic_tasks-0.1.0a3/django_periodic_tasks/__init__.py

@@ -0,0 +1,15 @@
+from django_periodic_tasks.decorators import exactly_once
+from django_periodic_tasks.registry import (
+    ScheduleEntry,
+    ScheduleRegistry,
+    schedule_registry,
+    scheduled_task,
+)
+
+__all__ = [
+    "ScheduleEntry",
+    "ScheduleRegistry",
+    "exactly_once",
+    "schedule_registry",
+    "scheduled_task",
+]

django_periodic_tasks-0.1.0a3/django_periodic_tasks/admin.py

@@ -0,0 +1,86 @@
+from typing import Any
+
+from django.contrib import admin
+from django.http import HttpRequest
+
+from django_periodic_tasks.models import ScheduledTask, TaskExecution
+
+# Fields that are always read-only (computed/tracking)
+TRACKING_READONLY = ("source", "last_run_at", "next_run_at", "total_run_count", "created_at", "updated_at")
+
+# All editable model fields
+ALL_FIELDS = (
+    "name",
+    "task_path",
+    "cron_expression",
+    "timezone",
+    "args",
+    "kwargs",
+    "source",
+    "enabled",
+    "queue_name",
+    "priority",
+    "backend",
+    "last_run_at",
+    "next_run_at",
+    "total_run_count",
+    "created_at",
+    "updated_at",
+)
+
+
+@admin.register(ScheduledTask)
+class ScheduledTaskAdmin(admin.ModelAdmin[ScheduledTask]):
+    list_display = (
+        "name",
+        "task_path",
+        "cron_expression",
+        "source",
+        "enabled",
+        "last_run_at",
+        "next_run_at",
+        "total_run_count",
+    )
+    list_filter = ("source", "enabled")
+    search_fields = ("name", "task_path")
+    ordering = ("name",)
+
+    def get_readonly_fields(
+        self,
+        request: HttpRequest,
+        obj: ScheduledTask | None = None,
+    ) -> tuple[str, ...]:
+        if obj is None:
+            # New task being created
+            return TRACKING_READONLY
+        if obj.source == ScheduledTask.Source.CODE:
+            # Code-defined tasks: everything is read-only
+            return ALL_FIELDS
+        # DB-defined tasks: only tracking fields are read-only
+        return TRACKING_READONLY
+
+    def has_delete_permission(
+        self,
+        request: HttpRequest,
+        obj: Any = None,
+    ) -> bool:
+        if obj is not None and obj.source == ScheduledTask.Source.CODE:
+            return False
+        return super().has_delete_permission(request, obj)
+
+
+@admin.register(TaskExecution)
+class TaskExecutionAdmin(admin.ModelAdmin[TaskExecution]):
+    list_display = ("id", "scheduled_task", "status", "created_at", "completed_at")
+    list_filter = ("status",)
+    search_fields = ("scheduled_task__name",)
+    ordering = ("-created_at",)
+
+    def has_add_permission(self, request: HttpRequest) -> bool:
+        return False
+
+    def has_change_permission(self, request: HttpRequest, obj: Any = None) -> bool:
+        return False
+
+    def has_delete_permission(self, request: HttpRequest, obj: Any = None) -> bool:
+        return False