# blocklint
[](https://badge.fury.io/py/blocklint)
[](https://github.com/PrincetonUniversity/blocklint)
[](https://github.com/PrincetonUniversity/blocklint)
[](https://github.com/PrincetonUniversity/blocklint/blob/master/LICENSE)
**blocklint** is a command line utility for finding non-inclusive wording.
This project is inspired by [Alex.js](https://alexjs.com).
## About
If you've used a modern IDE, you know the importance of immediate feedback
for compilation errors or even stylistic slip ups. Knowing all variables
should be declared or that lines must be less than 80 characters long is good,
but adhering to those rules takes a back seat when in the flow of writing
code. A linter brings these issues back into your consciousness by
highlighting the problematic lines of code. Over time, the enforced style
becomes more intuitive but the linter is always there to nudge you if you slip.
We are in the midst of changing attitudes towards words and phrases that are
not inclusive. Not only are developers acknowledging the offensive history of
terms like "master/slave" and "blacklist/whitelist", but we are taking active
steps to remove their usage and replace them with more appropriate language.
This tool is not a commentary on inclusion, but rather a utility to detect
whatever words you'd like to remove from code.
[Alex.js](https://alexjs.com) is one option for highlighting offensive language,
but it is geared towards text documents such as markdown, misses common
constructs in source code and is also overly broad and prone to false
positives. Blocklint is built with source code in mind and is more limited
in scope.
## Requirements and Installation
Blocklint is written in python and uses minimal, standard libraries. It has
been tested for python >= 3.7 To install:
```
pip install blocklint
```
into an appropriate environment.
## Usage
Without any arguments, blocklint will search all files in the current directory
for uses of master, slave, blacklist and whitelist:
```bash
$ pwd
/path/to/blocklint/blocklint
$ blocklint
/path/to/blocklint/blocklint/main.py:40:60: use of "blacklist"
/path/to/blocklint/blocklint/main.py:40:37: use of "master"
/path/to/blocklint/blocklint/main.py:40:44: use of "slave"
/path/to/blocklint/blocklint/main.py:40:50: use of "whitelist"
/path/to/blocklint/blocklint/main.py:55:53: use of "blacklist"
/path/to/blocklint/blocklint/main.py:55:30: use of "master"
/path/to/blocklint/blocklint/main.py:55:37: use of "slave"
/path/to/blocklint/blocklint/main.py:55:43: use of "whitelist"
```
Optionally, multiple files and directories can be specified to search. The
detected words can be customized through several options; setting any will
clear the defaults. Multiple words are specified as comma separated values:
- blocklist: Will match any occurrence of the word, ignoring case and special
characters.
- wordlist: Will match the word, ignoring case and special characters but
respecting word boundaries.
- exactlist: Will match the word as entered respecting word boundaries.
Only the first match of a word in a line will be returned, but multiple words
can match on a single line. Here are some examples:
```bash
$ blocklint --blocklist test,asdf <(echo thisTEST will match as will a_S-d:F)
/dev/fd/63:1:29: use of "asdf"
/dev/fd/63:1:5: use of "test"
$ blocklint --wordlist test,asdf <(echo thisTEST will not match but T=E-ST, will)
/dev/fd/63:1:29: use of "test"
$ blocklint --exactlist Test <(echo thisTest, tEST, T-est fail but Test! matches)
/dev/fd/63:1:32: use of "Test"
```
The `-e,--end-pos` flag will provide the end position of the match in addition
to the start position.
The `--stdin` flag will take values from stdin instead of a file or directory.
The `--skip-files` flag takes a comma-or-newline separated list of paths to files
that should not be checked by blocklint. This is useful when running blocklint on
a large directory.
## Configuration
Blocklint supports the standard `ini` configuration format used by many other
linting tools, including
[flake8](https://flake8.pycqa.org/en/latest/user/configuration.html).
Command line arguments have highest priority, and override any arguments derived
from configuration files. Next highest are local files `tox.ini`, `setup.cfg`,
and `.blocklint`. Finally, a global config in `~/.blocklint` may be used.
Config files should contain a blocklint section in ini format, for example:
```
[blocklint]
max_issue_threshold=10
blocklist=test,asdf
end_pos=store_true
```
Other example blocklists can be found [here](https://contentdesign.intuit.com/accessibility-and-inclusion/abolish-racist-language/#harmful-words).
## Skipping lines
In addition to skipping entire files with the `--skip-files` option, single
lines can be skipped by including the (regex) phrase `blocklint:.*pragma`.
For example:
```python
def main(blacklist, white_list): # blocklint: pragma
for item in blacklist: # blocklint: some other information pragma
...
```
will pass all checks.
## Integrations
The integration directory contains information on using blocklint for:
- [ALE](https://github.com/dense-analysis/ale)
- [pre-commit](https://pre-commit.com/)
Don't see the tool you use? Submit a pull request or issue!
Raw data
{
"_id": null,
"home_page": "https://github.com/PrincetonUniversity/blocklint",
"name": "blocklint",
"maintainer": null,
"docs_url": null,
"requires_python": "!=3.0,!=3.1,!=3.2,!=3.3,!=3.4,>=2.7",
"maintainer_email": null,
"keywords": null,
"author": "Troy Comi",
"author_email": "tcomi@princeton.edu",
"download_url": "https://files.pythonhosted.org/packages/a0/94/57d3020226a2bab2bd7db41eac864dbb63602efb883809a3fc6347736be9/blocklint-0.2.5.tar.gz",
"platform": null,
"description": "# blocklint\n[](https://badge.fury.io/py/blocklint)\n[](https://github.com/PrincetonUniversity/blocklint)\n[](https://github.com/PrincetonUniversity/blocklint)\n[](https://github.com/PrincetonUniversity/blocklint/blob/master/LICENSE)\n\n**blocklint** is a command line utility for finding non-inclusive wording.\nThis project is inspired by [Alex.js](https://alexjs.com).\n\n## About\nIf you've used a modern IDE, you know the importance of immediate feedback\nfor compilation errors or even stylistic slip ups. Knowing all variables\nshould be declared or that lines must be less than 80 characters long is good,\nbut adhering to those rules takes a back seat when in the flow of writing\ncode. A linter brings these issues back into your consciousness by\nhighlighting the problematic lines of code. Over time, the enforced style\nbecomes more intuitive but the linter is always there to nudge you if you slip.\n\nWe are in the midst of changing attitudes towards words and phrases that are\nnot inclusive. Not only are developers acknowledging the offensive history of\nterms like \"master/slave\" and \"blacklist/whitelist\", but we are taking active\nsteps to remove their usage and replace them with more appropriate language.\nThis tool is not a commentary on inclusion, but rather a utility to detect\nwhatever words you'd like to remove from code.\n\n[Alex.js](https://alexjs.com) is one option for highlighting offensive language,\nbut it is geared towards text documents such as markdown, misses common\nconstructs in source code and is also overly broad and prone to false\npositives. Blocklint is built with source code in mind and is more limited\nin scope.\n\n## Requirements and Installation\nBlocklint is written in python and uses minimal, standard libraries. It has\nbeen tested for python >= 3.7 To install:\n\n```\npip install blocklint\n```\ninto an appropriate environment.\n\n## Usage\nWithout any arguments, blocklint will search all files in the current directory\nfor uses of master, slave, blacklist and whitelist:\n```bash\n$ pwd\n/path/to/blocklint/blocklint\n$ blocklint\n/path/to/blocklint/blocklint/main.py:40:60: use of \"blacklist\"\n/path/to/blocklint/blocklint/main.py:40:37: use of \"master\"\n/path/to/blocklint/blocklint/main.py:40:44: use of \"slave\"\n/path/to/blocklint/blocklint/main.py:40:50: use of \"whitelist\"\n/path/to/blocklint/blocklint/main.py:55:53: use of \"blacklist\"\n/path/to/blocklint/blocklint/main.py:55:30: use of \"master\"\n/path/to/blocklint/blocklint/main.py:55:37: use of \"slave\"\n/path/to/blocklint/blocklint/main.py:55:43: use of \"whitelist\"\n```\n\nOptionally, multiple files and directories can be specified to search. The\ndetected words can be customized through several options; setting any will\nclear the defaults. Multiple words are specified as comma separated values:\n - blocklist: Will match any occurrence of the word, ignoring case and special\n characters.\n - wordlist: Will match the word, ignoring case and special characters but\n respecting word boundaries.\n - exactlist: Will match the word as entered respecting word boundaries.\n\nOnly the first match of a word in a line will be returned, but multiple words\ncan match on a single line. Here are some examples:\n```bash\n$ blocklint --blocklist test,asdf <(echo thisTEST will match as will a_S-d:F)\n/dev/fd/63:1:29: use of \"asdf\"\n/dev/fd/63:1:5: use of \"test\"\n\n$ blocklint --wordlist test,asdf <(echo thisTEST will not match but T=E-ST, will)\n/dev/fd/63:1:29: use of \"test\"\n\n$ blocklint --exactlist Test <(echo thisTest, tEST, T-est fail but Test! matches)\n/dev/fd/63:1:32: use of \"Test\"\n```\nThe `-e,--end-pos` flag will provide the end position of the match in addition\nto the start position.\n\nThe `--stdin` flag will take values from stdin instead of a file or directory.\n\nThe `--skip-files` flag takes a comma-or-newline separated list of paths to files\nthat should not be checked by blocklint. This is useful when running blocklint on\na large directory.\n\n## Configuration\n\nBlocklint supports the standard `ini` configuration format used by many other\nlinting tools, including\n[flake8](https://flake8.pycqa.org/en/latest/user/configuration.html).\n\nCommand line arguments have highest priority, and override any arguments derived\nfrom configuration files. Next highest are local files `tox.ini`, `setup.cfg`,\nand `.blocklint`. Finally, a global config in `~/.blocklint` may be used.\n\nConfig files should contain a blocklint section in ini format, for example:\n\n```\n[blocklint]\nmax_issue_threshold=10\nblocklist=test,asdf\nend_pos=store_true\n```\n\nOther example blocklists can be found [here](https://contentdesign.intuit.com/accessibility-and-inclusion/abolish-racist-language/#harmful-words).\n\n## Skipping lines\nIn addition to skipping entire files with the `--skip-files` option, single\nlines can be skipped by including the (regex) phrase `blocklint:.*pragma`.\nFor example:\n```python\ndef main(blacklist, white_list): # blocklint: pragma\n for item in blacklist: # blocklint: some other information pragma\n ...\n```\nwill pass all checks.\n\n## Integrations\nThe integration directory contains information on using blocklint for:\n- [ALE](https://github.com/dense-analysis/ale)\n- [pre-commit](https://pre-commit.com/)\n\nDon't see the tool you use? Submit a pull request or issue!\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Lint for blocklisted words.",
"version": "0.2.5",
"project_urls": {
"Homepage": "https://github.com/PrincetonUniversity/blocklint"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ea61c782cd48f81b1e4641adcdc817bfc97bc4dca28e8f5405ccf3005fc8c590",
"md5": "967cf19624c31f4bb52e5eb0e69b60eb",
"sha256": "c1ee4169551bf04043ad23d3e502df1481ff39118e667da4682136370f1dfd11"
},
"downloads": -1,
"filename": "blocklint-0.2.5-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "967cf19624c31f4bb52e5eb0e69b60eb",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": "!=3.0,!=3.1,!=3.2,!=3.3,!=3.4,>=2.7",
"size": 8373,
"upload_time": "2024-04-06T09:46:48",
"upload_time_iso_8601": "2024-04-06T09:46:48.641226Z",
"url": "https://files.pythonhosted.org/packages/ea/61/c782cd48f81b1e4641adcdc817bfc97bc4dca28e8f5405ccf3005fc8c590/blocklint-0.2.5-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a09457d3020226a2bab2bd7db41eac864dbb63602efb883809a3fc6347736be9",
"md5": "2c6fbb92071dc385b95008b2f03c95c3",
"sha256": "a80db6f4d32707b80d4a1be338630a64fbd2dda3b3ac07193f0a128d930b2716"
},
"downloads": -1,
"filename": "blocklint-0.2.5.tar.gz",
"has_sig": false,
"md5_digest": "2c6fbb92071dc385b95008b2f03c95c3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "!=3.0,!=3.1,!=3.2,!=3.3,!=3.4,>=2.7",
"size": 17957,
"upload_time": "2024-04-06T09:46:50",
"upload_time_iso_8601": "2024-04-06T09:46:50.237152Z",
"url": "https://files.pythonhosted.org/packages/a0/94/57d3020226a2bab2bd7db41eac864dbb63602efb883809a3fc6347736be9/blocklint-0.2.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-06 09:46:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "PrincetonUniversity",
"github_project": "blocklint",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "blocklint"
}
JSON
