# OLX Cleaner
[](https://github.com/openedx/olxcleaner/actions/workflows/ci.yaml) [](https://codecov.io/gh/jolyonb/olxcleaner)
This library aims to perform two functions:
* Parse the XML code for an edX course, loading it into python objects
* Validate the objects for errors
Based on this, two scripts are provided that leverage the library:
* `edx-cleaner` constructs an error report, course tree and course statistics
* `edx-reporter` constructs a LaTeX file representation of the course structure
Copyright (C) 2018-2019 Jolyon Bloomfield
Copyright (C) 2020-2023 The Center for Reimagining Learning, Inc. and Contributors
## Links
* [Error Listing](errors.md)
* [Wishlist](wishlist.md)
* [Vision](vision.md)
* [Changelog](changelog.md)
* [License](LICENSE)
## Installation
This package may be installed from PYPI using `pip install olxcleaner`. It requires python 3.6 or later.
### Repository Installation (advanced)
Clone this repository, and set up a virtual environment for python 3.6 or later. Run `pip install -r requirements.txt` to install the libraries, followed by `pytest` to ensure that all tests are passing as expected.
## edx-cleaner Usage
Used to validate OLX (edX XML) code. This is a very light wrapper around the olxcleaner library, but exposes all of the functionality thereof.
Basic usage: run `edx-cleaner` in the directory of the course you want to validate.
Command-line options:
```text
edx-cleaner [-h]
[-c COURSE]
[-p {1,2,3,4,5,6,7,8}]
[-t TREE] [-l {0,1,2,3,4}]
[-q] [-e] [-s] [-S]
[-f {0,1,2,3,4}]
[-i IGNORE [IGNORE ...]]
```
* `-h`: Display help.
* `-c`: Specify the course file to analyze. If not specified, looks for `course.xml` in the current directory. If given a directory, looks for `course.xml` in that directory.
* `-p`: Specify the validation level you wish analyze the course at:
* 1: Load the course
* 2: Load the policy and grading policy
* 3: Validate url_names
* 4: Merge policy data with course, ensuring that all references are valid
* 5: Validate the grading policy
* 6: Have every object validate itself
* 7: Parse the course for global errors
* 8: Parse the course for detailed global errors (default)
* `-t TREE`: Specify a file to output the tree structure to.
* `-l`: Specify the depth level to output the tree structure to. Only used if the `-t` option is set. 0 = Course, 1 = Chapter, 2 = Sequential, 3 = Vertical, 4 = Content.
* `-q`: Quiet mode. Does not output anything to the screen.
* `-e`: Suppress error listing. Implied by `-q`.
* `-s`: Suppress summary of errors. Implied by `-q`.
* `-S`: Display course statistics (off by default). Overridden by `-q`.
* `-f`: Select the error level at which to exit with an error code. 0 = DEBUG, 1 = INFO, 2 = WARNING, 3 = ERROR (default), 4 = NEVER. Exit code is set to `1` if an error at the specified level or higher is present.
* `-i`: Specify a space-separated list of error names to ignore. See [Error Listing](errors.md).
## edx-reporter Usage
The olxcleaner library includes modules that parse a course into python objects. This can be useful if you want to scan a course to generate a report. We exploit this in `edx-reporter` to generate a LaTeX report of course structure.
Basic usage: run `edx-reporter` in the directory of the course you want to generate a report about.
Command-line options:
```text
edx-reporter.py [-h]
[-c COURSE]
[-u]
[> latexfile.tex]
```
* `-h`: Display help.
* `-c`: Specify the course file to analyze. If not specified, looks for `course.xml` in the current directory. If given a directory, looks for `course.xml` in that directory.
* `-u`: Include url_names for verticals.
* `> latexfile.tex`: Output the report to a file.
If you get an error like ``Character cannot be encoded into LaTeX: U+FEFF - `'``, then you have some bad unicode in your `display_name` entries. Look through the LaTeX output for `{\bfseries ?}`, which is what that character is converted into.
Once you have generated a latex file, you can compile it into a PDF file by running `pdflatex latexfile.tex`. Note that the latex file can be modified with any text editor; its format should be self-explanatory.
## Library usage
The workhorse of the library is `olxcleaner.validate`, which validates a course in a number of steps.
```python
olxcleaner.validate(filename, steps=8, ignore=None, allowed_xblocks=None)
```
* `filename`: Pass in either the course directory or the path of `course.xml` for the course you wish to validate.
* `steps`: Choose how many validation steps you wish to perform:
* 1: Load the course
* 2: Load the policy and grading policy
* 3: Validate `url_name`s
* 4: Merge policy data with course, ensuring that all references are valid
* 5: Validate the grading policy
* 6: Have every object validate itself
* 7: Parse the course for global errors
* 8: Parse the course for global errors that may be time-consuming to detect
* `ignore`: A list of error names to ignore
* `allowed_xblocks`: A list of all allowed xblocks that course olx may contain.
Returns `EdxCourse`, `ErrorStore`, `url_names` (dictionary `{'url_name': EdxObject}`, or `None` if `steps < 3`)
See examples of how to use `olxcleaner.validate` and the objects it returns in `olxcleaner.entries`.
Raw data
{
"_id": null,
"home_page": "https://github.com/openedx/olxcleaner",
"name": "olxcleaner",
"maintainer": "",
"docs_url": null,
"requires_python": "~=3.6",
"maintainer_email": "",
"keywords": "edx",
"author": "Jolyon Bloomfield",
"author_email": "jolyon@mit.edu",
"download_url": "https://files.pythonhosted.org/packages/cf/81/ba246a479498ffbc7e19615605934190fd1ae2799de636c01678524a1a0f/olxcleaner-0.2.1.tar.gz",
"platform": null,
"description": "# OLX Cleaner\n\n[](https://github.com/openedx/olxcleaner/actions/workflows/ci.yaml) [](https://codecov.io/gh/jolyonb/olxcleaner)\n\nThis library aims to perform two functions:\n\n* Parse the XML code for an edX course, loading it into python objects\n* Validate the objects for errors\n\nBased on this, two scripts are provided that leverage the library:\n\n* `edx-cleaner` constructs an error report, course tree and course statistics\n* `edx-reporter` constructs a LaTeX file representation of the course structure\n\nCopyright (C) 2018-2019 Jolyon Bloomfield\n\nCopyright (C) 2020-2023 The Center for Reimagining Learning, Inc. and Contributors\n\n## Links\n\n* [Error Listing](errors.md)\n* [Wishlist](wishlist.md)\n* [Vision](vision.md)\n* [Changelog](changelog.md)\n* [License](LICENSE)\n\n## Installation\n\nThis package may be installed from PYPI using `pip install olxcleaner`. It requires python 3.6 or later.\n\n### Repository Installation (advanced) \n\nClone this repository, and set up a virtual environment for python 3.6 or later. Run `pip install -r requirements.txt` to install the libraries, followed by `pytest` to ensure that all tests are passing as expected.\n\n## edx-cleaner Usage\n\nUsed to validate OLX (edX XML) code. This is a very light wrapper around the olxcleaner library, but exposes all of the functionality thereof.\n\nBasic usage: run `edx-cleaner` in the directory of the course you want to validate.\n\nCommand-line options:\n\n```text\nedx-cleaner [-h] \n [-c COURSE]\n [-p {1,2,3,4,5,6,7,8}] \n [-t TREE] [-l {0,1,2,3,4}]\n [-q] [-e] [-s] [-S]\n [-f {0,1,2,3,4}]\n [-i IGNORE [IGNORE ...]]\n```\n\n* `-h`: Display help.\n* `-c`: Specify the course file to analyze. If not specified, looks for `course.xml` in the current directory. If given a directory, looks for `course.xml` in that directory.\n* `-p`: Specify the validation level you wish analyze the course at:\n * 1: Load the course\n * 2: Load the policy and grading policy\n * 3: Validate url_names\n * 4: Merge policy data with course, ensuring that all references are valid\n * 5: Validate the grading policy\n * 6: Have every object validate itself\n * 7: Parse the course for global errors\n * 8: Parse the course for detailed global errors (default)\n* `-t TREE`: Specify a file to output the tree structure to.\n* `-l`: Specify the depth level to output the tree structure to. Only used if the `-t` option is set. 0 = Course, 1 = Chapter, 2 = Sequential, 3 = Vertical, 4 = Content. \n* `-q`: Quiet mode. Does not output anything to the screen.\n* `-e`: Suppress error listing. Implied by `-q`.\n* `-s`: Suppress summary of errors. Implied by `-q`.\n* `-S`: Display course statistics (off by default). Overridden by `-q`.\n* `-f`: Select the error level at which to exit with an error code. 0 = DEBUG, 1 = INFO, 2 = WARNING, 3 = ERROR (default), 4 = NEVER. Exit code is set to `1` if an error at the specified level or higher is present.\n* `-i`: Specify a space-separated list of error names to ignore. See [Error Listing](errors.md).\n\n## edx-reporter Usage\n\nThe olxcleaner library includes modules that parse a course into python objects. This can be useful if you want to scan a course to generate a report. We exploit this in `edx-reporter` to generate a LaTeX report of course structure.\n\nBasic usage: run `edx-reporter` in the directory of the course you want to generate a report about.\n\nCommand-line options:\n\n```text\nedx-reporter.py [-h] \n [-c COURSE]\n [-u]\n [> latexfile.tex]\n```\n\n* `-h`: Display help.\n* `-c`: Specify the course file to analyze. If not specified, looks for `course.xml` in the current directory. If given a directory, looks for `course.xml` in that directory.\n* `-u`: Include url_names for verticals.\n* `> latexfile.tex`: Output the report to a file.\n\nIf you get an error like ``Character cannot be encoded into LaTeX: U+FEFF - `'``, then you have some bad unicode in your `display_name` entries. Look through the LaTeX output for `{\\bfseries ?}`, which is what that character is converted into.\n\nOnce you have generated a latex file, you can compile it into a PDF file by running `pdflatex latexfile.tex`. Note that the latex file can be modified with any text editor; its format should be self-explanatory.\n\n## Library usage\n\nThe workhorse of the library is `olxcleaner.validate`, which validates a course in a number of steps.\n\n```python\nolxcleaner.validate(filename, steps=8, ignore=None, allowed_xblocks=None)\n```\n\n* `filename`: Pass in either the course directory or the path of `course.xml` for the course you wish to validate.\n* `steps`: Choose how many validation steps you wish to perform:\n * 1: Load the course\n * 2: Load the policy and grading policy\n * 3: Validate `url_name`s\n * 4: Merge policy data with course, ensuring that all references are valid\n * 5: Validate the grading policy\n * 6: Have every object validate itself\n * 7: Parse the course for global errors\n * 8: Parse the course for global errors that may be time-consuming to detect\n* `ignore`: A list of error names to ignore\n* `allowed_xblocks`: A list of all allowed xblocks that course olx may contain.\n\nReturns `EdxCourse`, `ErrorStore`, `url_names` (dictionary `{'url_name': EdxObject}`, or `None` if `steps < 3`)\n\nSee examples of how to use `olxcleaner.validate` and the objects it returns in `olxcleaner.entries`.\n\n\n",
"bugtrack_url": null,
"license": "LICENSE",
"summary": "Tool to scan Open edX courses for various errors",
"version": "0.2.1",
"split_keywords": [
"edx"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2c837e98588133965f3db83eb57791c4536946008dcb6fc77e0513005e4de79a",
"md5": "679998833e119bede639053b65786e70",
"sha256": "a446c8c18a8638513a904b219e6606e2c2a295015dcd3a4ec5540449ccbebf92"
},
"downloads": -1,
"filename": "olxcleaner-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "679998833e119bede639053b65786e70",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "~=3.6",
"size": 57023,
"upload_time": "2023-02-03T21:36:26",
"upload_time_iso_8601": "2023-02-03T21:36:26.250804Z",
"url": "https://files.pythonhosted.org/packages/2c/83/7e98588133965f3db83eb57791c4536946008dcb6fc77e0513005e4de79a/olxcleaner-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cf81ba246a479498ffbc7e19615605934190fd1ae2799de636c01678524a1a0f",
"md5": "2319660964255ba0626f421f787c515e",
"sha256": "d857534b5594f7c08e2246059f6ea6d7a0c0766242e55b338365d8fa05f06c67"
},
"downloads": -1,
"filename": "olxcleaner-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "2319660964255ba0626f421f787c515e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "~=3.6",
"size": 47265,
"upload_time": "2023-02-03T21:36:27",
"upload_time_iso_8601": "2023-02-03T21:36:27.371107Z",
"url": "https://files.pythonhosted.org/packages/cf/81/ba246a479498ffbc7e19615605934190fd1ae2799de636c01678524a1a0f/olxcleaner-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-02-03 21:36:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "openedx",
"github_project": "olxcleaner",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [
{
"name": "lxml",
"specs": [
[
"==",
"4.2.5"
]
]
},
{
"name": "python-dateutil",
"specs": [
[
"==",
"2.8.0"
]
]
},
{
"name": "pytz",
"specs": [
[
"==",
"2019.1"
]
]
},
{
"name": "pylatexenc",
"specs": [
[
"==",
"1.5"
]
]
},
{
"name": "pytest",
"specs": [
[
"==",
"4.6.4"
]
]
},
{
"name": "pytest-cov",
"specs": [
[
"==",
"2.7.1"
]
]
},
{
"name": "twine",
"specs": []
}
],
"lcname": "olxcleaner"
}
JSON
