openedx / edx-lint

Custom tooling for pylint and other repo management tools

edx-lint

_

A collection of code quality tools:

• A few pylint plugins to check for quality issues pylint misses.
• A command-line tool to generate config files like pylintrc from a master file (part of edx_lint), and a repo-specific tweaks file.

Using edx_lint

The edx_lint command can generate config files from its own master file. Install the package using pip:

$ pip install edx-lint

The write sub-command will write a config file based on the contents of the edx_lint master file:

$ edx_lint write pylintrc

The file written contains a hash of its contents, to detect subsequent editing. edx_lint will detect this when it next tries to write the file. If editing is detected, the edited file will be moved aside so it can be compared to the newly written file.

Handling newly introduced lint violations

New potential lint violations will be communicated with a major version bump.

If you run into new lint violations during an upgrade of edx-lint, your options include:

1. Fixing the violations immediately, or
2. Using lint-amnesty and fixing at a later time, or
3. Customizing edx_lint to permanently ignore the violations.

Using lint-amnesty

The lint-amnesty command can be used to squash all existing pylint errors in a codebase, so that from then the repository can maintain pylint-cleanliness. Install the package using pip:

$ pip install edx-lint

The lint-amnesty command expects pylint errors in the --output-format=parseable format:

$ pylint my.python.package --output-format=parseable | lint-amnesty

This will add comments for every existing pylint violation that look like:

# pylint: disable=some-error  # lint-amnesty

It will also remove any existing suppressions that pylint flags as being useless-suppressions.

Customizing edx_lint

You can customize the resulting pylintrc file by creating a pylintrc_tweaks file in the current directory before running the write sub-command. It should contain only the settings you want to override.

Note: If your project is not a Django project, you'll want to disable the Django plugins with your pylintrc_tweaks file:

[MASTER]
load-plugins = edx_lint.pylint

Developing edx_lint

To run the tests:

$ make requirements
$ make test

To manually test your pylint plugin, create a custom module and run pylint with a selected set of enabled message symbols. For instance:

pylint --load-plugins=edx_lint.pylint --disable=all --enable=feature-toggle-needs-doc path/to/my/custom/module.py

License

The code in this repository is licensed under Apache 2.0. Please see LICENSE.txt for details.

How To Contribute

Contributions are very welcome.

Please read How To Contribute for details.

Getting Help

The Open edX project has resources for developer support on the Getting Help page.

edx-lint's Issues

DeprecationWarning: invalid escape sequence \c in test/plugins/pylint_test.py

https://travis-ci.com/cclauss/edx-lint/jobs/180003543#L247-L248

test/plugins/pylint_test.py::test_that_we_can_test_pylint
  <unknown>:12: DeprecationWarning: invalid escape sequence \c

https://github.com/edx/edx-lint/blob/master/test/plugins/pylint_test.py

Remove Sphinx Common Constraint

Description

• PR #306 added Sphinx in common constraints

TODO

• Investigate if it is safe to remove the common constraint now
• Create follow up PR in edx-platform to test that the new version does not conflicts with any other package.

Remove pylint<2.15.0 constraint

Description

• pylint>2.15.0 contains breaking changes so it was pinned in the PR #290.

TODO

• Remove the pylint constraint
• Fix all reported warnings
• Release new edx-lint release by upgrading the tag.

Use ranges for dependencies

This package requires pylint 1.4.4. We are using pylint 1.5.1 for course-discovery. There is no need to require a specific version a pylint. Use a range (e.g. pylint>=1.4.4,<2.0.0) instead for all dependencies.

Errors in Python 3.12

While attempting to upgrade a project to Py3.12 I started getting this error in quality checks:

Command line or configuration file:1:0: E0013: Plugin 'edx_lint.pylint' is impossible to load, is it installed ? ('No module named 'pkg_resources'') (bad-plugin-value)

Older versions of Python passed as usual. It looks like pkg_resources has been superseded by importlib.resources, at least for the calls we're using it for in this repository. It should support back to Python 3.7.

I'm hoping to have a PR for this in the near term, but in case someone runs into this sooner it should be an easy fix. I don't know if there are other 3.12 issues behind it, though.

[Discovery] Improve common constraints experience

Issue description and initial comments moved from private ticket: https://2u-internal.atlassian.net/browse/BOM-2721

The process around common_constraints.txt has some issues as we work through upgrades.

1. It is not simple to override a common constraint in constraints.txt, which is where you might expect to do this when working through an upgrade that isn't yet available globally.
2. It is not clear how to mark and clean-up overrides once the common constraints can finally be removed.

See openedx/auth-backends#125 (comment) for some related discussion.

Additional Notes:

• Some related docs updates:
  • Reminder: If we are making changes to a library based on a new or updated api in a dependency, we need to add and comment a new minimum requirement in base.in.
  • If we know that a library will break with an updated dependency, we should add a maximum constraint in to the library’s base.in, and not just rely on common_constraints.txt.
  • If we release an updated library that fixes and uses a newer version of a dependency that is in common_constraints.txt, we either need to:
    • remove the dependency from common_constraints.txt (if we are ready), or
    • add a maximum constraint to common_constraints.txt for the library update, so no one will try to pick up the new version of the library which will conflict with the active common constraint on the dependency.
      • See example: #182

Chained comparisons cause incorrect warnings

This line of code:

assertTrue(0 <= npoints <= 1)

causes:

[C7690(wrong-assert-type), CustomResponseTest.test_function_code_single_input] assertTrue(0 <= npoints <= 1) should be assertLessEqual

Add support for latest versions of packages

Packages:

• astroid-1.6.1
• pylint-1.8.2
• pylint-django-0.9.0

This is by today. Tomorrow it may change. But it is better to be up to date with latest pylint

Remove pylint_django plugin

The pylint_django plugin is required (https://github.com/edx/edx-lint/blob/96f4c58137f73bd4798400c4107dbf1a422dc34f/edx_lint/files/pylintrc#L22), but is not included as a dependency of this package. Unless this is intended only for Django projects, pylint_django should not be a default plugin.

Layered test checker doesn't diagnose three-layer cakes

This code runs two tests in nose and pytest:

# Three-layer cake.

class BaseTest(unittest.TestCase):
    __test__ = False
    def test_it(self):
        self.fail("Hello, world!")

class Middle(BaseTest):
    __test__ = True

class MoreTests(Middle):
    __test__ = True

but the layered test checker doesn't detect it.

Unpin tox

We pinned tox back in December because the 4.0.0 release broke most of our CI runs. It's quite possible that this has been resolved by now, so we should attempt to remove this pin (requested by Axim in https://openedx.slack.com/archives/C0497NQCLBT/p1682004301805179).

Proposed A/C:

• Use the workaround from the Slack thread above to allow upgrading tox in edx-platform (chosen because it's the repo most likely to hit nasty corner cases in almost any upgrade). If CI fails with the latest version, spend a little time attempting to resolve.
• If we can get edx-platform CI working with the latest tox release, merge the PR with those changes. If any changes were needed which are also likely to be needed in other repos upgrading to the latest version, announce them via all appropriate communications channels.
• If all the above goes well, remove the pin from common_constraints.txt so other repos can upgrade tox normally.
• Remove the edx-platform workaround for the common tox constraint, if it was merged.

Fix test_pylintrc_file_created

#38 introduced a test to test the edx_lint write pylintrc command. For an unknown reason, the command fails to run with tox. It does work when run outside of tox (e.g. with PyCharm). Make it work with tox, and remove the skip decorator.

edx_lint command no longer installed

Affects >=1.3.1

The edx_lint command wrapper around edx_lint.cmd.main no longer seems to be installed.

Add tox support

Use tox to support local testing with multiple versions of Python.

Setup Travis

• Automate tests
• Automate pushes to PyPI

Suggestion: Bump edx-lint major version when upgrading to stricter pylint

1.3.0 used pylint 1.7.6, while 1.4.1 uses pylint 2+

Pylint 2+ features some errors and warnings that did not appear in pylint 1.7.6. This is good an alll, but it's a breaking change for repos that require a 10/10 pylint score on PRs. Per semver, we should bump the edx-lint major version in the future.

Unpin importlib-metadata

In #406 we pinned importlib-metadata to before 7.x. Once open-telemetry/opentelemetry-python#3570 resolves we should unpin this.

This pin is in place because we want to use opentelemetry from edx-django-utils. Normally this could be added as a constraint in edx-django-utils, where we're adding the opentelemetry dependency. However, when we compile pip-tools.txt in dependent IDA repos, that layer ends up using version 7.x, and then there's no undoing that when compiling base.txt. So we need to pin it globally, for now.

Find incorrect context managers

At Python Study Group this week, we looked at context managers. When we got to @contextlib.contextmanager, we learned that this is wrong:

@contextmanager
def my_context_manager():
    #... set up
    yield
    #... clean up

because the clean up won't execute if an exception happens inside the caller's with-statement.

I grepped edx-platform to see if this happens, and it does! here and here for example.

We also have instances of pointless context managers with no clean up at all (here):

@contextmanager
def lti_consumer_fields_editing_flag(course_id, enabled_for_course=False):
    """
    Yields CourseEditLTIFieldsEnabledFlag record for unit tests

    Arguments:
        course_id (CourseLocator): course locator to control this feature for.
        enabled_for_course (bool): whether feature is enabled for 'course_id'
    """
    RequestCache.clear_all_namespaces()
    CourseEditLTIFieldsEnabledFlag.objects.create(course_id=course_id, enabled=enabled_for_course)
    yield

It would be cool to lint for these mistakes.

BTW: A reason to have a cleanup-less context manager is in a method overriding a correct context manager, but the subclass needs no clean up. If we write this linter, that case can use a disabling pragma.

/cc @cpennington @jmbowman @bessiesteinberg

Ignore common Django files/directories

We have ignore=migrations, settings, wsgi.py in edx/ecommerce. I'd like to continue ignoring these for new IDAs.

Upgrade Django constraint to <5

The current common_constraints used across the org pins Django to <4:
https://github.com/openedx/edx-lint/blob/master/edx_lint/files/common_constraints.txt

Since edx-platform is on 4.2 and other upgrades are in progress, we should upgrade this to <5 as soon as possible so we're testing with the correct versions across all projects.

Add support for Python 3

I'd like to use Python 3 for new IDAs, and want to include this package. Update it to support Python 3.

Remove platformdirs global constraint

Description

• tox>4.0 requires platformdirs==4.0.0 and virtualenv requires platformdirs<4.0 which conflict and cause the requirements upgrade build to fail.
• To resolve the failing build process and upgrade tox version, the platformdirs<4.0 constraint has been added globally.

TODO

• Remove this constraint once the issue pypa/virtualenv#2666 is completed and a new release of virtualenv>20.24.6 is out.

Suggestion: warn on use of sys.exit

sys.exit is probably wrong in most places in edx code. It's almost always better to just raise an exception. In particular, in management commands, you should raise a CommandError so that callers using the command via call_command don't have the process shut down underneath them.