diff --git a/README.rst b/README.rst index af6d363..543f04e 100644 --- a/README.rst +++ b/README.rst @@ -1,6 +1,14 @@ =========== EOX Tagging =========== +|Maintainance Badge| |Test Badge| |PyPI Badge| + +.. |Maintainance Badge| image:: https://img.shields.io/badge/Status-Maintained-brightgreen + :alt: Maintainance Status +.. |Test Badge| image:: https://img.shields.io/github/actions/workflow/status/edunext/eox-tagging/.github%2Fworkflows%2Ftests.yml?label=Test + :alt: GitHub Actions Workflow Test Status +.. |PyPI Badge| image:: https://img.shields.io/pypi/v/eox-tagging?label=PyPI + :alt: PyPI - Version Eox-tagging is an `openedx plugin`_, part of the Edunext Open Extensions (aka EOX), that adds the capability to tag `edx-platform`_ objects. These tags can be used to categorize, include extra information, and so on. @@ -23,27 +31,27 @@ Installation Compatibility Notes -------------------- -+-------------------+----------------+ -| Open edX Release | Version | -+===================+================+ -| Ironwood | < 0.9 < 3.0 | -+-------------------+----------------+ -| Juniper | >= 0.9 < 3.0 | -+-------------------+----------------+ -| Koa | >= 2.2 < 5.0 | -+-------------------+----------------+ -| Lilac | >= 2.2 < 5.0 | -+-------------------+----------------+ -| Maple | >= 4.0 < 6.0 | -+-------------------+----------------+ -| Nutmeg | >= 5.0 < 6.0 | -+-------------------+----------------+ -| Olive | >= 5.0 < 6.0 | -+-------------------+----------------+ -| Palm | >= 6.0 | -+-------------------+----------------+ -| Quince | >= 7.0 | -+-------------------+----------------+ ++------------------+--------------+ +| Open edX Release | Version | ++==================+==============+ +| Ironwood | < 0.9 < 3.0 | ++------------------+--------------+ +| Juniper | >= 0.9 < 3.0 | ++------------------+--------------+ +| Koa | >= 2.2 < 5.0 | ++------------------+--------------+ +| Lilac | >= 2.2 < 5.0 | ++------------------+--------------+ +| Maple | >= 4.0 < 6.0 | ++------------------+--------------+ +| Nutmeg | >= 5.0 < 6.0 | ++------------------+--------------+ +| Olive | >= 5.0 < 6.0 | ++------------------+--------------+ +| Palm | >= 6.0 | ++------------------+--------------+ +| Quince | >= 7.0 | ++------------------+--------------+ The following changes to the plugin settings are necessary. If the release you are looking for is not listed, then the accumulation of changes from previous releases is enough. @@ -56,21 +64,21 @@ not listed, then the accumulation of changes from previous releases is enough. EOX_TAGGING_GET_COURSE_OVERVIEW: "eox_tagging.edxapp_wrappers.backends.course_overview_i_v1" EOX_TAGGING_BEARER_AUTHENTICATION: "eox_tagging.edxapp_wrappers.backends.bearer_authentication_i_v1" -**Koa, Lilac, Maple, Nutmeg, Olive, Palm and Quince** +**Koa, Lilac, Maple, Nutmeg, Olive** .. code-block:: yaml EOX_TAGGING_GET_ENROLLMENT_OBJECT: "eox_tagging.edxapp_wrappers.backends.enrollment_l_v1" -Those settings can be changed in ``eox_tagging/settings/common.py`` or, for example, in ansible configurations. +Those settings can be changed in ``eox_tagging/settings/common.py`` or the instance settings. -**NOTE**: the current ``common.py`` works with Open edX Lilac version. +**NOTE**: the current ``common.py`` works with Open edX Quince and Palm versions. Usage ====== -See the `How to section `_ for detailed guidance on Model, configurations and API usage. +See the `How to section `_ for detailed guidance on model, configurations and API usage. Important notes: ---------------- @@ -86,18 +94,18 @@ Examples .. code-block:: JSON { - "validate_tag_value":{ - "in":[ + "validate_tag_value": { + "in": [ "example_tag_value", "example_tag_value_1" ] }, - "validate_access":{ - "equals":"PRIVATE" + "validate_access": { + "equals": "PRIVATE" }, - "validate_target_object":"OpaqueKeyProxyModel", - "owner_object":"User", - "tag_type":"tag_by_example" + "validate_target_object": "OpaqueKeyProxyModel", + "owner_object": "User", + "tag_type": "tag_by_example" } This means that: @@ -113,7 +121,7 @@ This means that: .. code-block:: JSON { - "validate_tag_value":{ + "validate_tag_value": { "exist": true }, "validate_access": "Public", @@ -141,10 +149,10 @@ This means that: ] }, "validate_target_object": "CourseEnrollment", - "tag_type":"tag_by_edunext", - "validate_activation_date":{ + "tag_type": "tag_by_edunext", + "validate_activation_date": { "exist": true, - "in":[ + "in": [ "Dec 04 2020 10:30:40", "Oct 19 2020 10:30:40" ] @@ -157,14 +165,14 @@ This means that: * The field access can be `private` or `public`. * The target type must be equal to `CourseEnrollment` * Tag type must be equal to tag_by_edunext. -* The tag activation date must exist and be between the values defined in the array. This means: value_1 <= activation_date <= value_2. +* The tag activation date must exist between the values defined in the array. This means, value_1 <= activation_date <= value_2. The array must be sorted or a validation error will be raised. Tagging REST API ================ -Get list of tags ----------------- +Get a list of tags +------------------ **Request** @@ -287,12 +295,13 @@ Filters example usage: ``/eox_tagging/api/v1/tags/?enrollments=COURSE_ID`` -Auditing Django views (Optional in Maple) -========================================= +Auditing Django views +===================== The majority of views in eox-tagging use an auditing decorator, defined in our custom library called `eox-audit-model`_, -that helps save relevant information about non-idempotent operations. By default, this functionality is turned on. To -check your auditing records go to Django sysadmin and find DJANGO EDUNEXT AUDIT MODEL. +that helps save relevant information about non-idempotent operations. By default, this functionality is turned off, to enable it, install eox-audit-model. + +Check your auditing records in *Django sysadmin > DJANGO EDUNEXT AUDIT MODEL*. For more information, check the eox-audit-model documentation. @@ -309,3 +318,9 @@ information – it also contains guidelines for how to maintain high code quality, which will make your contribution more likely to be accepted. .. _CONTRIBUTING: https://github.com/eduNEXT/eox-tagging/blob/master/CONTRIBUTING.rst + + +License +======= + +This project is licensed under the AGPL-3.0 License. See the LICENSE file for details. \ No newline at end of file diff --git a/docs/how_to/api.rst b/docs/how_to/api.rst index bc2e130..3ed134c 100644 --- a/docs/how_to/api.rst +++ b/docs/how_to/api.rst @@ -10,13 +10,13 @@ Currently, to be able to use the API, the user must be authenticated. One of the any request to the tagging API. In the future, public -limited- access will be provided. As mentioned above, an authorization token can be provided as an Authorization HTTP header when calling the API. -If not, then the session authentication will be use. If any of this authentications work then the user won't be able to make any +If not, then the session authentication will be used. If any of these authentications work then the user won't be able to make any successful API call. API permission ^^^^^^^^^^^^^^^ -If a user wants to make API calls, in addition to being authenticated must have the custom eox-tagging permission so can make any write/read operations. -This permission iscalled `can_call_eox_tagging`. +If a user wants to make API calls, in addition to being authenticated, must have the custom eox-tagging permission so can make any write/read operations. +This permission is called `can_call_eox_tagging`. Possible API calls @@ -24,80 +24,80 @@ Possible API calls The tags are `immutable` by definition, so after creating a tag the only calls allowed are to list, get details and delete tags. -+---------------------------------+---------------------------------------------------+ -| Name | Description | -+=================================+===================================================+ -| list | Used to list all tags owned by the user making the| -| | API call. If the owner does not have any tags | -| | created yet, an empty set will be returned. | -+---------------------------------+---------------------------------------------------+ -| details | Used to get the information of a single tag. If | -| | the tag does not exist it returns Not Found. | -+---------------------------------+---------------------------------------------------+ -| delete | Used to deactivate an active tag. This implements | -| | a soft delete operation. | -+---------------------------------+---------------------------------------------------+ -| create | Used to create a tag. | -+---------------------------------+---------------------------------------------------+ ++---------+----------------------------------------------------+ +| Name | Description | ++=========+====================================================+ +| list | Used to list all tags owned by the user making the | +| | API call. If the owner does not have any tags | +| | created yet, an empty set will be returned. | ++---------+----------------------------------------------------+ +| details | Used to get the information of a single tag. If | +| | the tag does not exist it returns Not Found. | ++---------+----------------------------------------------------+ +| delete | Used to deactivate an active tag. This implements | +| | a soft delete operation. | ++---------+----------------------------------------------------+ +| create | Used to create a tag. | ++---------+----------------------------------------------------+ Serializer fields ------------------ -When creating a tag, this are the fields expected: - -+----------------------------------+--------------------------------------------------+------------------+ -| Field Name | Description | Required | -+==================================+==================================================+==================+ -| tag_type | Works as the class of the tag. | Yes | -+----------------------------------+--------------------------------------------------+------------------+ -| tag_value | It can be thought as the class instance. | Yes | -+----------------------------------+--------------------------------------------------+------------------+ -| access | Access level of the tag. | Yes | -+----------------------------------+--------------------------------------------------+------------------+ -| activation_date | Datetime when the tag will be activated. | No | -| | It can have UTC format or Year-Month-Day H:M:S | | -+----------------------------------+--------------------------------------------------+------------------+ -| expiration_date | Datetime when the tag will be deactivated. | No | -| | It can have UTC format or Year-Month-Day H:M:S | | -+----------------------------------+--------------------------------------------------+------------------+ -| target_type | Type of the target. Must be equal to: user, site,| Yes | -| | courseoverview or courseenrollment. | | -+----------------------------------+--------------------------------------------------+------------------+ -| target_id | ID of the target with type target_type. | Yes | -+----------------------------------+--------------------------------------------------+------------------+ -| owner_type | Type of the tag owner. If omitted, site will be | No | -| | as the owner | | -+----------------------------------+--------------------------------------------------+------------------+ - -When retrieving objects, the JSON object will have the following fields (the mentioned above and): - -+----------------------------------+---------------------------------------------------+ -| Field Name | Description | -+==================================+===================================================+ -| meta | Field with technical information, like dates and | -| | information about the target and the owner. | -+----------------------------------+---------------------------------------------------+ -| status | Status of the tag. This could be active or | -| | inactive. | -+----------------------------------+---------------------------------------------------+ -| key | UUID Public identifier. | -+----------------------------------+---------------------------------------------------+ +When creating a tag, these are the fields expected: + ++-----------------+--------------------------------------------------+----------+ +| Field Name | Description | Required | ++=================+==================================================+==========+ +| tag_type | Works as the class of the tag. | Yes | ++-----------------+--------------------------------------------------+----------+ +| tag_value | It can be thought as the class instance. | Yes | ++-----------------+--------------------------------------------------+----------+ +| access | Access level of the tag. | Yes | ++-----------------+--------------------------------------------------+----------+ +| activation_date | Datetime when the tag will be activated. | No | +| | It can have UTC format or Year-Month-Day H:M:S | | ++-----------------+--------------------------------------------------+----------+ +| expiration_date | Datetime when the tag will be deactivated. | No | +| | It can have UTC format or Year-Month-Day H:M:S | | ++-----------------+--------------------------------------------------+----------+ +| target_type | Type of the target. Must be equal to: user, site,| Yes | +| | courseoverview or courseenrollment. | | ++-----------------+--------------------------------------------------+----------+ +| target_id | ID of the target with type target_type. | Yes | ++-----------------+--------------------------------------------------+----------+ +| owner_type | Type of the tag owner. If omitted, site will be | No | +| | as the owner | | ++-----------------+--------------------------------------------------+----------+ + +When retrieving objects, the JSON object will have the following fields (and the mentioned above): + ++------------+---------------------------------------------------+ +| Field Name | Description | ++============+===================================================+ +| meta | Field with technical information, like dates and | +| | information about the target and the owner. | ++------------+---------------------------------------------------+ +| status | Status of the tag. This could be active or | +| | inactive. | ++------------+---------------------------------------------------+ +| key | UUID Public identifier. | ++------------+---------------------------------------------------+ Validations ----------- -During the creation process starts, it's checked that ``target_type`` exists, if not then the creation process is interrupted and an error -will be raised. This results in returning an object describing the error ocurred. After checking if the target_type exists, the model validations +The creation process check that ``target_type`` exists, if not this is interrupted and an error +will be raised, returning an object describing the error that occurred. After checking if the target_type exists, the model validations will be performed and if an error occurs the error message will be returned in a response instead of valid data. Examples -------- -Get list of tags -^^^^^^^^^^^^^^^^ +Get a list of tags +^^^^^^^^^^^^^^^^^^ **Request** @@ -129,7 +129,7 @@ Get list of tags } Create tag -^^^^^^^^^^^^^^^^ +^^^^^^^^^^ **Request** @@ -170,7 +170,7 @@ Where TAG_DATA: } Delete tag -^^^^^^^^^^^^^^^^ +^^^^^^^^^^ **Request** diff --git a/docs/how_to/configuration.rst b/docs/how_to/configuration.rst index 3f5c113..e368caa 100644 --- a/docs/how_to/configuration.rst +++ b/docs/how_to/configuration.rst @@ -24,7 +24,7 @@ Where can be any editable tag field, and any of the de Validations ^^^^^^^^^^^ -Here's how to create validated fields, first, add the key validate_ to the configuration dictionary, where: +Here's how to create validated fields, first, add the key ``validate_`` to the configuration dictionary, where: * The FIELD_VALUE must be a Tag field, if not an exception will be raised. @@ -133,18 +133,18 @@ Examples .. code-block:: JSON { - "validate_tag_value":{ - "in":[ + "validate_tag_value": { + "in": [ "example_tag_value", "example_tag_value_1" ] }, - "validate_access":{ - "equals":"PRIVATE" + "validate_access": { + "equals": "PRIVATE" }, - "validate_target_object":"OpaqueKeyProxyModel", - "owner_object":"User", - "tag_type":"tag_by_example" + "validate_target_object": "OpaqueKeyProxyModel", + "owner_object": "User", + "tag_type": "tag_by_example" } This means that: @@ -160,12 +160,12 @@ This means that: .. code-block:: JSON { - "validate_tag_value":{ - "exist":true + "validate_tag_value": { + "exist": true }, - "validate_access":"Public", - "validate_target_object":"User", - "tag_type":"tag_by_edunext" + "validate_access": "Public", + "validate_target_object": "User", + "tag_type": "tag_by_edunext" } This means that: @@ -180,18 +180,18 @@ This means that: .. code-block:: JSON { - "validate_tag_value":"tag_value", - "validate_access":{ - "in":[ + "validate_tag_value": "tag_value", + "validate_access": { + "in": [ "Private", "Public" ] }, - "validate_target_object":"CourseEnrollment", - "tag_type":"tag_by_edunext", - "validate_activation_date":{ - "exist":true, - "in":[ + "validate_target_object": "CourseEnrollment", + "tag_type": "tag_by_edunext", + "validate_activation_date": { + "exist": true, + "in": [ "Dec 04 2020 10:30:40", "Oct 19 2020 10:30:40" ] diff --git a/docs/how_to/model.rst b/docs/how_to/model.rst index 6a30a31..f81858c 100644 --- a/docs/how_to/model.rst +++ b/docs/how_to/model.rst @@ -9,32 +9,32 @@ A tag is an object created over a specified target by an entity called owner. Th Attributes ----------- -+--------------------------+----------------------------------------------------------------------------+ -| Name | Description | -+==========================+============================================================================+ -| tag_type | This attribute works as a category, it can be for example: | -| | `subscription_tier`. | -+--------------------------+----------------------------------------------------------------------------+ -| tag_value | Contains the value of the tag. This would be for `subscription_tier` | -| | the value `free`. | -+--------------------------+----------------------------------------------------------------------------+ -| access | The access level for the tag, it can be public, private and protected. This| -| | this defines the visibility of the tag to the users. The default is public.| -+--------------------------+----------------------------------------------------------------------------+ -| activation_date | Datetime when the tag will be activated. | -+--------------------------+----------------------------------------------------------------------------+ -| expiration_date | Datetime when the tag will be deactivated. | -+--------------------------+----------------------------------------------------------------------------+ -| created_at | Creation date. | -+--------------------------+----------------------------------------------------------------------------+ -| status | Current tag status, when created is ACTIVE, and when is deleted becomes | -| | an inactive tag. | -+--------------------------+----------------------------------------------------------------------------+ -| target_object | Represents the tag target, this can be a user, courseenrollment, site or | -| | course. | -+--------------------------+----------------------------------------------------------------------------+ -| owner_object | Represents the tag owner. This can be a user or site. | -+--------------------------+----------------------------------------------------------------------------+ ++-----------------+----------------------------------------------------------------------------+ +| Name | Description | ++=================+============================================================================+ +| tag_type | This attribute works as a category, it can be for example: | +| | `subscription_tier`. | ++-----------------+----------------------------------------------------------------------------+ +| tag_value | Contains the value of the tag. This would be for `subscription_tier` | +| | the value `free`. | ++-----------------+----------------------------------------------------------------------------+ +| access | The access level for the tag, it can be public, private and protected. This| +| | this defines the visibility of the tag to the users. The default is public.| ++-----------------+----------------------------------------------------------------------------+ +| activation_date | Datetime when the tag will be activated. | ++-----------------+----------------------------------------------------------------------------+ +| expiration_date | Datetime when the tag will be deactivated. | ++-----------------+----------------------------------------------------------------------------+ +| created_at | Creation date. | ++-----------------+----------------------------------------------------------------------------+ +| status | Current tag status, when created is ACTIVE, and when is deleted becomes | +| | an inactive tag. | ++-----------------+----------------------------------------------------------------------------+ +| target_object | Represents the tag target, this can be a user, courseenrollment, site or | +| | course. | ++-----------------+----------------------------------------------------------------------------+ +| owner_object | Represents the tag owner. This can be a user or site. | ++-----------------+----------------------------------------------------------------------------+ Validations