edx-milestones

2.0.0 verified Fri May 01 auth: no python

Provides models and utilities for tracking significant events (milestones) in Open edX courses, such as completion or certification eligibility. Current version 2.0.0, maintained under the Open edX organization. Release cadence is sporadic, with major version bumps tied to Python/Django support drops.

pip install edx-milestones

Common errors

error django.db.utils.OperationalError: no such table: milestones_milestone ↓

cause Missing migration. The milestones app must be included in INSTALLED_APPS and migrations must be run before using models.

fix

Run 'python manage.py migrate milestones' or include 'milestones' in INSTALLED_APPS and run 'python manage.py migrate'.

error AttributeError: module 'milestones' has no attribute 'api' ↓

cause Common mistake: importing api functions from the top-level package instead of milestones.api.

fix

Use correct import: from milestones.api import get_milestones_with_names

error ModuleNotFoundError: No module named 'milestones' ↓

cause The package is not installed or not in the Python path. Also, the Django app label is 'milestones' (plural), not 'milestone'.

fix

Install with 'pip install edx-milestones' and ensure it's added to INSTALLED_APPS as 'milestones'.

Warnings

breaking Dropped Python 3.11 support in v2.0.0. If your environment uses Python 3.11, do not upgrade beyond v1.1.0. ↓

fix Pin edx-milestones==1.1.0 in your requirements, or upgrade Python to 3.12+.

deprecated The milestone 'active' field is deprecated in favor of using queries based on literal values (True/False) instead of boolean field lookups to avoid table scans on Django 3.2+. ↓

fix Use Milestone.objects.filter(active=True) instead of .filter(active=1) or .filter(active__exact=True).

gotcha Milestone names are not unique by namespace: you can have multiple milestones with the same name in different namespaces. Always filter by both namespace and name to avoid unexpected duplicates. ↓

fix Use Milestone.objects.get(namespace='my_ns', name='milestone_name') instead of just name.

Imports

Milestone
```
from milestones.models import Milestone
```
Direct model import after app setup.
MilestoneRelationship
```
from milestones.models import MilestoneRelationship
```
Used to link milestones to courses or users.

get_milestones_with_names

wrong

from milestones import get_milestones_with_names

correct

from milestones.api import get_milestones_with_names

API functions live in milestones.api, not top-level.

Quickstart

Minimal Django setup to create a milestone record.

import django
from django.conf import settings
settings.configure(
    DATABASES={'default': {'ENGINE': 'django.db.backends.sqlite3', 'NAME': ':memory:'}},
    INSTALLED_APPS=['milestones'],
    USE_TZ=True,
)
django.setup()

from milestones.models import Milestone
m = Milestone.objects.create(
    namespace='test',
    name='middle_section',
    display_name='Middle Section',
    description='Complete the middle section of the course'
)
print(f'Created milestone: {m.id}')