pystrict3
----------
pystrict3 is a fast plausibility code analyser for Python3.
It checks code for obvious mistakes, such as
* calling declared and imported functions with a different number of arguments than they are defined with.
* accessing attributes and methods that are never set.
* documenting the wrong number of arguments (numpy or google style docstrings).
* using variables that were never set.
All this without running your python code!
This tool complements other static analysers such as pyflakes, and
can be used alongside linters and code format checkers (such as pylint and flake8).
.. image:: https://github.com/JohannesBuchner/pystrict3/actions/workflows/tests.yml/badge.svg
:target: https://github.com/JohannesBuchner/pystrict3/actions/workflows/tests.yml
.. image:: https://coveralls.io/repos/github/JohannesBuchner/pystrict3/badge.svg?branch=master
:target: https://coveralls.io/github/JohannesBuchner/pystrict3?branch=master
pystrict3 assumes that no monkey patching of builtin behaviour or
magic attributes (__dict__, __local__) alter classes and variables behind the scenes.
Python 3.5 and above is required.
Function calls
----------------
pystrict3 checks that functions are called with the
right number of arguments. This catches bugs before execution, for example
when call signatures change to include an additional argument::
def foo(a, b):
return a*b
foo(1, 2) ## OK
foo(123) ## error: wrong number of arguments
def bar(a, b=1):
return a*b
bar(1) ## OK
bar(1, 2) ## OK
bar(1, 2, 3) ## error: wrong number of arguments
# builtin module signatures are verified too:
import os, numpy
os.mkdir("foo", "bar") ## error: wrong number of arguments (if run with --load-builtin-modules)
numpy.exp() ## error: wrong number of arguments (if run with --load-any-modules)
pystrict3 checks that classes are instanciated with the right number of arguments,
methods are called with the right number of arguments, and
only attributes are accessed which have been assigned somewhere.
This catches bugs before execution, for example
when call signatures change to include an additional argument::
class Foo():
def __init__(self, a):
self.a = a
def foo(self):
self.b = 3
print(self.a) ## OK
def bar(self, c):
print(self.b) ## OK
return self.c ## error, because never assigned
Foo(1, 2) ## error: wrong number of arguments for __init__
foo = Foo(1) ## OK
# real example:
class Ellipse:
def __init__(self,center,radius_x,radius_y,fill_color,line_color,line_width):
self.center = center
self.radiusx = radius_x
self.radiusy = radius_y
self.fill_color = fill_color
self.line_color = line_color
self.line_width = line_width
def strarray(self):
return [" <ellipse cx=\"%d\" cy=\"%d\" rx=\"%d\" ry=\"%d\"\n" %\
(self.center[0],self.center[1],self.radius_x,self.radius_y),
" style=\"fill:%s;stroke:%s;stroke-width:%d\"/>\n" % (colorstr(self.fill_color),colorstr(self.line_color),self.line_width)]
# error above: self.radius_x vs self.radiusx
pystrict3 also checks docstrings for documented arguments and returns
(numpydoc, rst and google-style is supported).
It does not give an error if no docstrings are present.
However, if only part of the arguments are documented, it gives an
error pointing out the missing arguments to document.
For example::
def compute(num1, num2):
"""
Combined two integer numbers.
Parameters
----------
num1 : int
First number to add.
Returns
-------
sum: int
first number plus second number
int
first number minus second number
""":
return num1 + num2, num1 - num2, num1
This would raise two warnings:
1. parameter num2 is not documented
2. a triple is returned, but a tuple is documented.
Redefined variable
-------------------
pystrict3 (--allow-redefining disables this behaviour) can enforce that
variables are only assigned once.
This avoids changing the meaning of variables, and leads to cleaner, more idiomatic code
with fewer side-effects.
It also prevents overwriting python builtins. Some examples::
parse = parse(foo) ## bad
node = get_node()
node.foo() ## ok, modification
node += 3 ## ok, modification
def format(...): ## bad, format is a python keyword
import requests, html
html = requests.get(url) ## bad: overwrites imported package name
Contributing
--------------
Contributions are welcome.
pystrict3 may not catch all corner cases.
It tries hard to avoid unintentional false positives, and has a very
high code coverage with integration tests (see runtests.sh and tests/ directory).
Tested on activestate recipes, approximately half of all valid python3
programs are pystrict3 compliant, indicating that its guidelines
are already adhered to.
Install
-------
::
$ pip3 install pystrict3
Synapsis
--------
::
$ pystrict3.py --help
usage: pystrict3.py [-h] [--import-builtin] [--import-any] [--allow-redefining] [--verbose] filenames [filenames ...]
pystrict3: a Python code checker. Checks number of arguments in function, class init and method calls. Optionally also checks calls to imported modules. Checks that class attributes accessed are assigned somewhere. Checks that builtin names are
not overwritten. Checks that variables are only assigned once.
positional arguments:
filenames python files to parse
options:
-h, --help show this help message and exit
--import-builtin Also load builtin python modules to check function signatures. (default: False)
--import-any Also load any modules specified in import statements to check function signatures. Warning: can execute arbitrary module code. (default: False)
--allow-redefining Allow redefining variables. (default: False)
--verbose, -v More verbose logging output. (default: False)
Usage
--------
Run with::
$ python3 pystrict3.py <filenames>
$ python3 pystrict3.py --import-builtin <filenames>
$ python3 pystrict3.py --import-any <filenames>
Running with multiple filenames has the benefit that all
function signatures are first recorded and verified across all files.
Running with `--import-builtin` checks function calls to builtin
modules.
Running with `--import-any` checks function calls to any modules,
but this requires pystrict3 to import them, potentially running arbitrary
module code.
Example stderr outputs::
tests/expect-fail/recipe-412717.py:32: ERROR: Variable reuse: "Test"
tests/expect-fail/recipe-425043.py:13: ERROR: Function "pow" (3..3 arguments) called with 2 arguments
tests/expect-fail/recipe-578135.py:184: ERROR: Function "encode" (3..3 arguments) called with 2 arguments
Summary:
- checked 287 function calls.
- checked definition of 469 new and access of 393 variables.
- checked 4 docstrings.
pystrict3: OK
Return code is non-zero if a error was detected, or 0 otherwise.
For verbose output, pipe stdout to /dev/null.
gendocstr.py tool
-----------------
gendocstr.py pre-generates numpy-style docstrings.
Say you have a file with this code::
def indicator(r, threshold=42):
if r > threshold:
return False
else:
return True
Rewritten by gendocstr.py, the new code is::
def indicator(r, threshold=42):
"""<summary sentence of function in imperative>.
Parameters
-----------
r: <TYPE>
<MEANING OF r>
threshold: int
<MEANING OF threshold>
Returns
----------
indicator: bool
<MEANING OF indicator>
"""
if r > threshold:
return False
else:
return True
The following command creates a file myfile-new.py with suggested docstrings::
$ python3 gendocstr.py --verbose myfile.py
If you want to overwrite the source code file directly::
$ gendocstr.py --in-place myfile.py
**Features**:
* gendocstr.py can guess the parameter type from keywords and type annotations, if provided.
* can guess the return type if it is a input parameter or if it is True/False.
* keeps all the existing code formatting as is (thanks to `RedBaron <https://redbaron.readthedocs.io/en/latest/>`_).
* can be used together with isort and black to force normalised python code.
Licence
---------
BSD 2-clause.
Tipps
------
It's OK to have some pystrict3 warnings and errors. Take them as guidance towards
cleaner code.
How to write code that does not shadow or override variables:
* Use del to actively remove unused variables::
answer = input("Do you want to play? (yes/no)")
if answer == "no":
sys.exit()
del answer
answer = int(input("first value"))
print(answer * 10):
* Name parts of computation explicitly::
# bad:
magicnumber = sys.argv[1]
magicnumber = int(magicnumber)
# better:
magicnumberstr = sys.argv[1]
magicnumber = int(magicnumberstr)
filename = 'foo.pdf'
if condition:
filename = 'foo.png' # bad
# better:
if condition:
filename = 'foo.png'
else:
filename = 'foo.pdf'
# bad:
path = os.path.basename(sys.argv[1])
path = path + filename # bad: variable changes meaning
path = path + extension
# better:
components = []
components.append(os.path.basename(sys.argv[1]))
components.append(filename)
components.append(extension)
path = ''.join(components)
* Refactor into functions::
# original: "changes" is being reused.
USE_JYTHON = False
try:
# ... code detecting something, which throws an exception
USE_JYTHON = True ## re-assigning: not allowed
# could use instead:
# USE_JYTHON |= True
except:
pass
# or define a function
USE_JYTHON = check_jython()
# original: a sorting construct
changes = True
while changes:
changes = False
for a in ...:
if ...:
changes = True
break
if not changes:
break
# new: function returns when no further changes are needed
def mysort(objs):
while True:
changes = False
for a in ...:
if ...:
changes = True
break
if not changes:
return objs
* Instead of assigning to __doc__, move the docstring to the start of the file.
==============
Release Notes
==============
0.1.0 (2020-03-07)
------------------
* First version
Raw data
{
"_id": null,
"home_page": "https://github.com/JohannesBuchner/pystrict3",
"name": "pystrict3",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": null,
"author": "Johannes Buchner",
"author_email": "johannes.buchner.acad@gmx.com",
"download_url": "https://files.pythonhosted.org/packages/33/0e/d29044953d35db295985c243d24da80ba8b2c15b9e196355d0ff1b3df3c4/pystrict3-1.0.1.tar.gz",
"platform": null,
"description": "pystrict3\n----------\n\npystrict3 is a fast plausibility code analyser for Python3.\n\nIt checks code for obvious mistakes, such as\n\n* calling declared and imported functions with a different number of arguments than they are defined with.\n* accessing attributes and methods that are never set.\n* documenting the wrong number of arguments (numpy or google style docstrings).\n* using variables that were never set.\n\nAll this without running your python code!\n\nThis tool complements other static analysers such as pyflakes, and\ncan be used alongside linters and code format checkers (such as pylint and flake8).\n\n.. image:: https://github.com/JohannesBuchner/pystrict3/actions/workflows/tests.yml/badge.svg\n :target: https://github.com/JohannesBuchner/pystrict3/actions/workflows/tests.yml\n.. image:: https://coveralls.io/repos/github/JohannesBuchner/pystrict3/badge.svg?branch=master\n :target: https://coveralls.io/github/JohannesBuchner/pystrict3?branch=master\n\npystrict3 assumes that no monkey patching of builtin behaviour or\nmagic attributes (__dict__, __local__) alter classes and variables behind the scenes.\nPython 3.5 and above is required.\n\nFunction calls\n----------------\n\npystrict3 checks that functions are called with the\nright number of arguments. This catches bugs before execution, for example\nwhen call signatures change to include an additional argument::\n\n def foo(a, b):\n return a*b\n foo(1, 2) ## OK\n foo(123) ## error: wrong number of arguments\n\n def bar(a, b=1):\n return a*b\n bar(1) ## OK\n bar(1, 2) ## OK\n bar(1, 2, 3) ## error: wrong number of arguments\n \n # builtin module signatures are verified too:\n import os, numpy\n os.mkdir(\"foo\", \"bar\") ## error: wrong number of arguments (if run with --load-builtin-modules)\n numpy.exp() ## error: wrong number of arguments (if run with --load-any-modules)\n\n\npystrict3 checks that classes are instanciated with the right number of arguments,\nmethods are called with the right number of arguments, and\nonly attributes are accessed which have been assigned somewhere.\nThis catches bugs before execution, for example\nwhen call signatures change to include an additional argument::\n\n class Foo():\n def __init__(self, a):\n self.a = a\n def foo(self):\n self.b = 3\n print(self.a) ## OK\n def bar(self, c):\n print(self.b) ## OK\n return self.c ## error, because never assigned\n \n Foo(1, 2) ## error: wrong number of arguments for __init__\n foo = Foo(1) ## OK\n\n # real example:\n class Ellipse:\n def __init__(self,center,radius_x,radius_y,fill_color,line_color,line_width):\n self.center = center\n self.radiusx = radius_x\n self.radiusy = radius_y\n self.fill_color = fill_color\n self.line_color = line_color\n self.line_width = line_width\n def strarray(self):\n return [\" <ellipse cx=\\\"%d\\\" cy=\\\"%d\\\" rx=\\\"%d\\\" ry=\\\"%d\\\"\\n\" %\\\n (self.center[0],self.center[1],self.radius_x,self.radius_y),\n \" style=\\\"fill:%s;stroke:%s;stroke-width:%d\\\"/>\\n\" % (colorstr(self.fill_color),colorstr(self.line_color),self.line_width)]\n # error above: self.radius_x vs self.radiusx\n\npystrict3 also checks docstrings for documented arguments and returns\n(numpydoc, rst and google-style is supported).\nIt does not give an error if no docstrings are present. \nHowever, if only part of the arguments are documented, it gives an \nerror pointing out the missing arguments to document.\n\nFor example::\n\n def compute(num1, num2):\n \"\"\"\n Combined two integer numbers.\n\n Parameters\n ----------\n num1 : int\n First number to add.\n \n Returns\n -------\n sum: int\n first number plus second number\n int\n first number minus second number\n \"\"\":\n return num1 + num2, num1 - num2, num1\n\nThis would raise two warnings:\n\n1. parameter num2 is not documented\n2. a triple is returned, but a tuple is documented.\n\nRedefined variable\n-------------------\n\npystrict3 (--allow-redefining disables this behaviour) can enforce that \nvariables are only assigned once. \nThis avoids changing the meaning of variables, and leads to cleaner, more idiomatic code\nwith fewer side-effects.\n\nIt also prevents overwriting python builtins. Some examples::\n\n parse = parse(foo) ## bad\n node = get_node()\n node.foo() ## ok, modification\n node += 3 ## ok, modification\n\n def format(...): ## bad, format is a python keyword\n \n import requests, html\n \n html = requests.get(url) ## bad: overwrites imported package name\n\n\n\nContributing\n--------------\n\nContributions are welcome.\n\npystrict3 may not catch all corner cases.\nIt tries hard to avoid unintentional false positives, and has a very\nhigh code coverage with integration tests (see runtests.sh and tests/ directory).\n\nTested on activestate recipes, approximately half of all valid python3\nprograms are pystrict3 compliant, indicating that its guidelines\nare already adhered to.\n\nInstall\n-------\n::\n\n $ pip3 install pystrict3\n\n\nSynapsis\n--------\n::\n\n $ pystrict3.py --help\n\n usage: pystrict3.py [-h] [--import-builtin] [--import-any] [--allow-redefining] [--verbose] filenames [filenames ...]\n\n pystrict3: a Python code checker. Checks number of arguments in function, class init and method calls. Optionally also checks calls to imported modules. Checks that class attributes accessed are assigned somewhere. Checks that builtin names are\n not overwritten. Checks that variables are only assigned once.\n\n positional arguments:\n filenames python files to parse\n\n options:\n -h, --help show this help message and exit\n --import-builtin Also load builtin python modules to check function signatures. (default: False)\n --import-any Also load any modules specified in import statements to check function signatures. Warning: can execute arbitrary module code. (default: False)\n --allow-redefining Allow redefining variables. (default: False)\n --verbose, -v More verbose logging output. (default: False)\n\nUsage\n--------\n\nRun with::\n\n $ python3 pystrict3.py <filenames>\n $ python3 pystrict3.py --import-builtin <filenames>\n $ python3 pystrict3.py --import-any <filenames>\n\nRunning with multiple filenames has the benefit that all\nfunction signatures are first recorded and verified across all files.\n\nRunning with `--import-builtin` checks function calls to builtin\nmodules.\n\nRunning with `--import-any` checks function calls to any modules,\nbut this requires pystrict3 to import them, potentially running arbitrary\nmodule code.\n\n\nExample stderr outputs::\n\n tests/expect-fail/recipe-412717.py:32: ERROR: Variable reuse: \"Test\"\n tests/expect-fail/recipe-425043.py:13: ERROR: Function \"pow\" (3..3 arguments) called with 2 arguments\n tests/expect-fail/recipe-578135.py:184: ERROR: Function \"encode\" (3..3 arguments) called with 2 arguments\n Summary:\n - checked 287 function calls. \n - checked definition of 469 new and access of 393 variables.\n - checked 4 docstrings.\n pystrict3: OK\n\nReturn code is non-zero if a error was detected, or 0 otherwise.\n\nFor verbose output, pipe stdout to /dev/null.\n\ngendocstr.py tool\n-----------------\n\ngendocstr.py pre-generates numpy-style docstrings.\n\nSay you have a file with this code::\n\n def indicator(r, threshold=42):\n if r > threshold:\n return False\n else:\n return True\n\nRewritten by gendocstr.py, the new code is::\n\n def indicator(r, threshold=42):\n \"\"\"<summary sentence of function in imperative>.\n \n \n Parameters\n -----------\n r: <TYPE>\n <MEANING OF r>\n threshold: int\n <MEANING OF threshold>\n \n Returns\n ----------\n indicator: bool\n <MEANING OF indicator>\n \"\"\"\n if r > threshold:\n return False\n else:\n return True\n\nThe following command creates a file myfile-new.py with suggested docstrings::\n\n $ python3 gendocstr.py --verbose myfile.py\n\nIf you want to overwrite the source code file directly::\n\n $ gendocstr.py --in-place myfile.py\n\n**Features**:\n\n* gendocstr.py can guess the parameter type from keywords and type annotations, if provided. \n* can guess the return type if it is a input parameter or if it is True/False.\n* keeps all the existing code formatting as is (thanks to `RedBaron <https://redbaron.readthedocs.io/en/latest/>`_).\n* can be used together with isort and black to force normalised python code.\n\nLicence\n---------\n\nBSD 2-clause.\n\n\nTipps\n------\n\nIt's OK to have some pystrict3 warnings and errors. Take them as guidance towards\ncleaner code.\n\n\nHow to write code that does not shadow or override variables:\n\n* Use del to actively remove unused variables::\n \n answer = input(\"Do you want to play? (yes/no)\")\n if answer == \"no\":\n sys.exit()\n del answer\n answer = int(input(\"first value\"))\n print(answer * 10):\n\n* Name parts of computation explicitly::\n \n # bad:\n magicnumber = sys.argv[1]\n magicnumber = int(magicnumber)\n # better:\n magicnumberstr = sys.argv[1]\n magicnumber = int(magicnumberstr)\n \n \n filename = 'foo.pdf'\n if condition:\n filename = 'foo.png' # bad\n \n # better:\n if condition:\n filename = 'foo.png'\n else:\n filename = 'foo.pdf'\n \n # bad:\n path = os.path.basename(sys.argv[1])\n path = path + filename # bad: variable changes meaning\n path = path + extension\n\n # better:\n components = []\n components.append(os.path.basename(sys.argv[1]))\n components.append(filename)\n components.append(extension)\n path = ''.join(components)\n\n* Refactor into functions::\n\n # original: \"changes\" is being reused.\n USE_JYTHON = False\n try:\n # ... code detecting something, which throws an exception\n USE_JYTHON = True ## re-assigning: not allowed\n # could use instead:\n # USE_JYTHON |= True\n except:\n pass\n # or define a function\n USE_JYTHON = check_jython()\n \n # original: a sorting construct\n changes = True\n while changes:\n changes = False\n for a in ...:\n if ...:\n changes = True\n break\n if not changes:\n break\n \n # new: function returns when no further changes are needed\n def mysort(objs):\n while True:\n changes = False\n for a in ...:\n if ...:\n changes = True\n break\n if not changes:\n return objs\n\n* Instead of assigning to __doc__, move the docstring to the start of the file.\n\n\n==============\nRelease Notes\n==============\n\n0.1.0 (2020-03-07)\n------------------\n\n* First version\n\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "Static code analyser for Python3 function calls, string interpolation and variable shadowing",
"version": "1.0.1",
"project_urls": {
"Homepage": "https://github.com/JohannesBuchner/pystrict3"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "330ed29044953d35db295985c243d24da80ba8b2c15b9e196355d0ff1b3df3c4",
"md5": "5bf01f70638db851c8238cf8b4249401",
"sha256": "04198860f6145aac00fe884aa7b71e3aa6e60630025278e6cf84a6cdfdf6269e"
},
"downloads": -1,
"filename": "pystrict3-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "5bf01f70638db851c8238cf8b4249401",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 28293,
"upload_time": "2024-10-22T14:57:42",
"upload_time_iso_8601": "2024-10-22T14:57:42.542655Z",
"url": "https://files.pythonhosted.org/packages/33/0e/d29044953d35db295985c243d24da80ba8b2c15b9e196355d0ff1b3df3c4/pystrict3-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-22 14:57:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "JohannesBuchner",
"github_project": "pystrict3",
"travis_ci": true,
"coveralls": true,
"github_actions": true,
"lcname": "pystrict3"
}
JSON
