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

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.

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.

Setup Travis

• Automate tests
• Automate pushes to PyPI

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<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.

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.

[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

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.

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.

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.

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.

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.

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.

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

Add tox support

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

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.

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

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.

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.