Metadata-Version: 2.1
Name: edx-completion
Version: 4.6.0
Summary: A library for tracking completion of blocks by learners in edX courses.
Home-page: https://github.com/openedx/completion
Author: edX
Author-email: oscm@edx.org
License: AGPL 3.0
Keywords: Django edx
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
License-File: LICENSE
Requires-Dist: Django
Requires-Dist: XBlock >=1.2.2
Requires-Dist: django-model-utils
Requires-Dist: djangorestframework
Requires-Dist: edx-drf-extensions >=1.11.0
Requires-Dist: edx-opaque-keys
Requires-Dist: edx-toggles >=1.2.0
Requires-Dist: event-tracking
Requires-Dist: pytz
Requires-Dist: setuptools

completion
##########

|pypi-badge| |ci-badge| |codecov-badge| |doc-badge| |pyversions-badge|
|license-badge| |status-badge|

Purpose
*******

A library for tracking completion of blocks by learners in Open edX courses.

This repository provides a Django model `BlockCompletion` that is intended to be plugged into ``edx-platform``.  It
provides various handlers and services for the recording of completion data.  It also provides a DRF API for submitting
completion data in batches.

Enabling in the LMS
*******************

By default, the Open edX LMS does not use this library. To turn it on, go to http://your.lms.site/admin/waffle/switch/, and add a new switch with Name ``completion.enable_completion_tracking`` and Active selected.

See `Completion Tool <https://edx.readthedocs.io/projects/open-edx-building-and-running-a-course/en/latest/exercises_tools/completion.html>`_ in the Open edX documentation for details on what will happen once enabled.

Getting Started with Development
********************************

Please see the Open edX documentation for `guidance on Python development <https://docs.openedx.org/en/latest/developers/how-tos/get-ready-for-python-dev.html>`_ in this repo.

To install the ``completion`` app, run these commands from the `completion` root directory:

.. code:: bash

    pip install -e


To run the test suite:

.. code:: bash

    pip install tox
    tox # to run only a single environment, do e.g. tox -e py38-django42-drflatest


To use a Django shell to test commands:

.. code:: bash

    make install
    python manage.py migrate
    python manage.py shell
    >>> from completion.models import BlockCompletion
    >>> <other commands...>


Deploying
*********

Tagged versions of the completion library are released to pypi.org.

To use the latest release in your project, add the following to your pip requirements file:

.. code:: bash

    edx-completion

Getting Help
************

Documentation
=============

Start by going through `the documentation`_ (generated from `/docs </docs/index.rst>`_).  If you need more help see below.

.. _the documentation: https://docs.openedx.org/projects/completion

License
*******

The code in this repository is licensed under version 3 of the AGPL unless
otherwise noted.

Please see `LICENSE <LICENSE>`_ for details.

Contributing
************

Contributions are very welcome.
Please read `How To Contribute <https://openedx.org/r/how-to-contribute>`_ for details.

This project is currently accepting all types of contributions, bug fixes,
security fixes, maintenance work, or new features.  However, please make sure
to have a discussion about your new feature idea with the maintainers prior to
beginning development to maximize the chances of your change being accepted.
You can start a conversation by creating a new issue on this repo summarizing
your idea.

The Open edX Code of Conduct
****************************

All community members are expected to follow the `Open edX Code of Conduct`_.

.. _Open edX Code of Conduct: https://openedx.org/code-of-conduct/

People
******

The assigned maintainers for this component and other project details may be
found in `Backstage`_. Backstage pulls this data from the ``catalog-info.yaml``
file in this repo.

.. _Backstage: https://backstage.openedx.org/catalog/default/component/completion

Reporting Security Issues
*************************

Please do not report security issues in public. Please email security@openedx.org.

.. |pypi-badge| image:: https://img.shields.io/pypi/v/edx-completion.svg
    :target: https://pypi.python.org/pypi/edx-completion/
    :alt: PyPI

.. |ci-badge| image:: https://github.com/openedx/completion/actions/workflows/ci.yml/badge.svg?branch=master
    :target: https://github.com/openedx/completion/actions/workflows/ci.yml?branch=master
    :alt: CI

.. |codecov-badge| image:: http://codecov.io/github/edx/completion/coverage.svg?branch=master
    :target: http://codecov.io/github/edx/completion?branch=master
    :alt: Codecov

.. |doc-badge| image:: https://readthedocs.org/projects/completion/badge/?version=latest
    :target: https://docs.openedx.org/projects/completion
    :alt: Documentation

.. |pyversions-badge| image:: https://img.shields.io/pypi/pyversions/edx-completion.svg
    :target: https://pypi.python.org/pypi/edx-completion/
    :alt: Supported Python versions

.. |license-badge| image:: https://img.shields.io/github/license/edx/completion.svg
    :target: https://github.com/openedx/completion/blob/master/LICENSE.txt
    :alt: License

.. .. |status-badge| image:: https://img.shields.io/badge/Status-Experimental-yellow
.. |status-badge| image:: https://img.shields.io/badge/Status-Maintained-brightgreen
.. .. |status-badge| image:: https://img.shields.io/badge/Status-Deprecated-orange
.. .. |status-badge| image:: https://img.shields.io/badge/Status-Unsupported-red


Change Log
==========

..
   All enhancements and patches to completion will be documented
   in this file.  It adheres to the structure of http://keepachangelog.com/ ,
   but in reStructuredText instead of Markdown (for ease of incorporation into
   Sphinx documentation and the PyPI description).

   This project adheres to Semantic Versioning (http://semver.org/).

.. There should always be an "Unreleased" section for changes pending release.

[4.6.0] - 2024-4-16
-------------------

* Add support for Python 3.11 and 3.12

[4.5.0] - 2024-3-19
--------------------
* Added ``clear_learning_context_completion`` to enable clearing a learner's
  completion for a course

[4.4.1] - 2023-10-27
--------------------
* Fix RemovedInDjango41Warning by removing `django_app_config`

[4.4.0] - 2023-10-20
--------------------
* Added tracking logs for completion events

[4.3.0]- 2023-07-26
------------------------------------------------
* Added support for Django 4.2

[4.2.1]- 2023-04-26
------------------------------------------------
* Support ``get_child_blocks`` along with ``get_child_descriptors``.
* Switch from ``edx-sphinx-theme`` to ``sphinx-book-theme`` since the former is
  deprecated

[4.1.0]- 2021-07-19
------------------------------------------------
* Add Django 3.0, 3.1 & 3.2 Support

[4.0.4]- 2021-02-04
------------------------------------------------
* Update ``get_key_to_last_completed_block`` to return ``full_block_key`` instead of ``block_key``

[4.0.2] - 2021-02-04
------------------------------------------------
* Future-proof usage of ``edx_toggles.toggles``


[4.0.1] - 2021-01-05
------------------------------------------------
* Replace reference to deprecated import path ``student.models``
  with ``common.djangoapps.student.models``.
* Updated the build status badge in README.rst to point to travis-ci.com instead of travis-ci.org


[4.0.0] - 2020-11-05
------------------------------------------------
* Remove soon-to-be-deprecated WaffleSwitchNamespace class instances
* BACKWARD INCOMPATIBLE: Removes ``waffle()``, which returned a (now deprecated) WaffleSwitchNamespace. This should only affect tests in edx-platform.
* Requires edx-toggles>=1.2.0, which introduces a new API to waffle objects.
* Refactors ``ENABLE_COMPLETION_TRACKING_SWITCH`` from a ``LegacyWaffleSwitch`` to the updated ``WaffleSwitch``.  We don't expect uses of this updated switch to require changes, unless there are surprise uses of deprecated methods from ``LegacyWaffleSwitch``.

[3.2.5] - 2020-10-23
------------------------------------------------
* Fix waffle switch override in tests by relying on newest edx_toggles API

[3.2.4] - 2020-07-21
------------------------------------------------
* Fix AttributeError raised by `vertical_is_complete`.
  * by ensuring `get_completable_children` doesn't return null

[3.2.3] - 2020-07-01
------------------------------------------------
* Updated the children lookup for `vertical_is_complete` to utilize the XBlockCompletion model. There are
  three completion modes to consider: EXCLUDED, AGGREGATOR, COMPLETABLE.

  * This method will now ignore any block with XBlockCompletion.EXCLUDED.
  * This method will now recurse down any child of a vertical if that child has XBlockCompletion.AGGREGATOR.
  * This method will consider all children blocks with XBlockCompletion.COMPLETABLE as candidates to
    determine if the vertical is complete.

[3.2.2] - 2020-06-30
------------------------------------------------
* Adding recursive lookup for children of a vertical to the `vertical_is_complete` method in services.py.

  * This was added because verticals containing children that had their own children were not being properly marked
    as complete. Since the vertical was only looking one layer deep, it was possible to have children lower in the tree
    incomplete, but the vertical would still be marked as complete. Now it looks at all leaves under the vertical.

[3.1.1] - 2020-02-24
------------------------------------------------
* Remove unnecessary constraint for edx-drf-extensions<3.0.0

[3.1.0] - 2020-02-18
------------------------------------------------
* Upgrades packages, drops support for Python 2.

[3.0.1] - 2019-10-22
------------------------------------------------
* Fix the package long description to be valid rST, check this in CI.

[3.0.0] - 2019-10-22
------------------------------------------------
* Support tracking completion of XBlocks in any "learning context", such as in
  a content library, and not just in courses. To keep the code clean, this has
  been done as a **breaking change** to the python API. (The API has been
  simplified so that it's generally only necessary to pass in a block key /
  usage key rather than block key + course key.) The REST API is unchanged.

[2.1.1] - 2019-10-21
------------------------------------------------
* Updated credentials for PyPI deployment via token.

[2.1.0] - 2019-10-18
------------------------------------------------
* Switch blocks_to_mark_complete_on_view() to return a list of XBlocks instead of a set.  Many XBlocks aren't hashable;
  the old implementation allowed subtle bugs under Python 2.7 but triggers an immediate error under 3.5.

[2.0.0] - 2019-04-23
------------------------------------------------
* Unpin django-rest-framework requirements. This is a potentially **breaking change** if people were
  relying on this package to ensure the correct version of djangorestframework was being installed.
* Remove the AUTHORS file and references to it.

[1.0.2] - 2019-03-11
------------------------------------------------

* Fix the 403 error occurring for completion-batch API for requests coming from the iOS devices

[1.0.0] - 2018-10-16
------------------------------------------------
* Updated edx-drf-extensions imports. Completion will no longer work with
  outdated versions of edx-drf-extensions.

[0.1.14] - 2018-10-04
------------------------------------------------
* Added submit_completion and submit_group_completion methods on
  CompletionService.

[0.1.7] - 2018-06-18
------------------------------------------------
* Added can_mark_block_complete_on_view() and blocks_to_mark_complete_on_view()
  methods on CompletionService and renamed get_completion_by_viewing_delay_ms()
  to get_complete_on_view_delay_ms().

[0.1.6] - 2018-04-13
------------------------------------------------
* Remove usage of deprecated CourseStructure api.

[0.1.5] - 2018-04-03
------------------------------------------------
* Delete enable_visual_progress methods and checks. Deprecate ENABLE_VISUAL_PROGRESS,
  ENABLE_COURSE_VISUAL_PROGRESS, and ENABLE_SITE_VISUAL_PROGRESS waffle flags

[0.1.4] - 2018-03-28
------------------------------------------------
* Site configurations must now explicitly disable visual progress for the
  enable_visual_progress() feature gating function to return False early.

[0.1.3] - 2018-03-26
------------------------------------------------
* Added some documentation.

[0.1.2] - 2018-03-23
------------------------------------------------
* Fix management of dependency versions

[0.1.1] - 2018-03-23
------------------------------------------------
* Fixes wildly inefficient raw query in BlockCompletion.latest_blocks_completed_all_courses()
* Updates freezegun version, makes tests that use it somewhat faster.

[0.1.0] - 2018-03-20
------------------------------------------------
* Fixes https://openedx.atlassian.net/browse/EDUCATOR-2540

[0.0.11] - 2018-03-20
------------------------------------------------
* Added "subsection-completion/{username}/{course_key}/{subsection_id}" API
  endpoint, to be used with the completion milestones experiment.

[0.0.9] - 2018-02-27
------------------------------------------------
* Added "utilities.py", which houses methods for working with BlockCompletion
  data.

[0.0.8] - 2018-03-01
------------------------------------------------
* Add model method for superlative “last completed block” - for site awareness
  include every last completed block by course, for later sorting in business
  layer.

[0.0.7] - 2018-02-15
------------------------------------------------
* Add settings and service method for determining completion-by-viewing delay.

[0.0.6] - 2018-02-13
------------------------------------------------
* Add the additional completion logic into the service and models from edx-platform

[0.0.2] - 2018-01-31
------------------------------------------------
* Fix up edx-lint requirements shenanigans.

[0.0.1] - 2018-01-31
------------------------------------------------
* Initial release
