| Name | removestar JSON |
| Version |
1.5.2
JSON |
| download |
| home_page | None |
| Summary | A tool to automatically replace 'import *' imports with explicit imports in files |
| upload_time | 2024-11-25 15:38:25 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.7 |
| license | MIT |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# removestar
[![Actions Status][actions-badge]][actions-link]
[![PyPI version][pypi-version]][pypi-link]
[![Anaconda-Server Badge][conda-version]][conda-link]
[![PyPI platforms][pypi-platforms]][pypi-link]
[![Downloads][pypi-downloads]][pypi-link]
[![Conda Downloads][conda-downloads]][conda-link]
[![Ruff][ruff-badge]][ruff-link]
<!-- TODO:
[![pre-commit.ci status][pre-commit-badge]][pre-commit-link]
[![codecov percentage][codecov-badge]][codecov-link]
[![GitHub Discussion][github-discussions-badge]][github-discussions-link]
-->
Tool to automatically replace `import *` imports in Python files with explicit imports
## Installation
Install `removestar` globally to use it through CLI using `pypi` -
```bash
pip install removestar
pip install "removestar[nb]" # notebook support
```
or `conda` -
```bash
conda install -c conda-forge removestar
```
or add `removestar` in `.pre-commit-config.yaml` -
```yaml
- repo: https://github.com/asmeurer/removestar
rev: "1.5"
hooks:
- id: removestar
args: [-i] # See docs for all args (-i edits file in-place)
additional_dependencies: # The libraries or packages your code imports
- ... # Add . if running inside a library (to install the library itself in the environment)
- ... # Add nbformat and nbconvert for notebook support
```
## Usage
### pre-commit hook
Once `removestar` is added in `.pre-commit-config.yaml`, executing the following
will always run it (and other pre-commits) before every commit -
```bash
pre-commit install
```
Optionally, the pre-commits (including `removestar`) can be manually triggered for
all the files using -
```bash
pre-commit run --all-files
```
### CLI
```bash
# scripts
$ removestar file.py # Shows diff but does not edit file.py
$ removestar -i file.py # Edits file.py in-place
$ removestar -i module/ # Modifies every Python file in module/ recursively
# notebooks (make sure nbformat and nbconvert are installed)
$ removestar file.ipynb # Shows diff but does not edit file.ipynb
$ removestar -i file.ipynb # Edits file.ipynb in-place
```
## Why is `import *` so bad?
Doing `from module import *` is generally frowned upon in Python. It is
considered acceptable when working interactively at a `python` prompt, or in
`__init__.py` files (removestar skips `__init__.py` files by default).
Some reasons why `import *` is bad:
- It hides which names are actually imported.
- It is difficult both for human readers and static analyzers such as
pyflakes to tell where a given name comes from when `import *` is used. For
example, pyflakes cannot detect unused names (for instance, from typos) in
the presence of `import *`.
- If there are multiple `import *` statements, it may not be clear which names
come from which module. In some cases, both modules may have a given name,
but only the second import will end up being used. This can break people's
intuition that the order of imports in a Python file generally does not
matter.
- `import *` often imports more names than you would expect. Unless the module
you import defines `__all__` or carefully `del`s unused names at the module
level, `import *` will import every public (doesn't start with an
underscore) name defined in the module file. This can often include things
like standard library imports or loop variables defined at the top-level of
the file. For imports from modules (from `__init__.py`), `from module import
*` will include every submodule defined in that module. Using `__all__` in
modules and `__init__.py` files is also good practice, as these things are
also often confusing even for interactive use where `import *` is
acceptable.
- In Python 3, `import *` is syntactically not allowed inside of a function.
Here are some official Python references stating not to use `import *` in
files:
- [The official Python
FAQ](https://docs.python.org/3/faq/programming.html?highlight=faq#what-are-the-best-practices-for-using-import-in-a-module):
> In general, don’t use `from modulename import *`. Doing so clutters the
> importer’s namespace, and makes it much harder for linters to detect
> undefined names.
- [PEP 8](https://www.python.org/dev/peps/pep-0008/#imports) (the official
Python style guide):
> Wildcard imports (`from <module> import *`) should be avoided, as they
> make it unclear which names are present in the namespace, confusing both
> readers and many automated tools.
Unfortunately, if you come across a file in the wild that uses `import *`, it
can be hard to fix it, because you need to find every name in the file that is
imported from the `*`. Removestar makes this easy by finding which names come
from `*` imports and replacing the import lines in the file automatically.
One exception where `import *` can be bneficial:
At the early stages of code development, a definite set of required
functions can be difficult to determine. In such a context, wildcard imports could be
beneficial by avoiding constantly curating the set of required functions. For example,
at the development stage usage of `from os.path import *` can save time from curating
required functions. Post-development, the wld card imports could be determined using
`removestar`. Having said that, because of the multiple said reasons, wildcard imports
should be avoided.
## Example
Suppose you have a module `mymod` like
```bash
mymod/
| __init__.py
| a.py
| b.py
```
With
```py
# mymod/a.py
from .b import *
def func(x):
return x + y
```
```py
# mymod/b.py
x = 1
y = 2
```
Then `removestar` works like:
```bash
$ removestar mymod/
--- original/mymod/a.py
+++ fixed/mymod/a.py
@@ -1,5 +1,5 @@
# mymod/a.py
-from .b import *
+from .b import y
def func(x):
return x + y
```
This does not edit `a.py` by default. The `-i` flag causes it to edit `a.py` in-place:
```bash
$ removestar -i mymod/
$ cat mymod/a.py
# mymod/a.py
from .b import y
def func(x):
return x + y
```
## Command line options
<!-- TODO: Autogenerate this somehow -->
```bash
$ removestar --help
usage: removestar [-h] [-i] [--version] [--no-skip-init]
[--no-dynamic-importing] [-v] [-q]
[--max-line-length MAX_LINE_LENGTH]
PATH [PATH ...]
Tool to automatically replace "import *" imports with explicit imports
Requires pyflakes.
Usage:
$ removestar file.py # Shows diff but does not edit file.py
$ removestar -i file.py # Edits file.py in-place
$ removestar -i module/ # Modifies every Python file in module/ recursively
positional arguments:
PATH Files or directories to fix
optional arguments:
-h, --help show this help message and exit
-i, --in-place Edit the files in-place. (default: False)
--version Show removestar version number and exit.
--no-skip-init Don't skip __init__.py files (they are skipped by
default) (default: True)
--no-dynamic-importing
Don't dynamically import modules to determine the list
of names. This is required for star imports from
external modules and modules in the standard library.
(default: True)
-v, --verbose Print information about every imported name that is
replaced. (default: False)
-q, --quiet Don't print any warning messages. (default: False)
--max-line-length MAX_LINE_LENGTH
The maximum line length for replaced imports before
they are wrapped. Set to 0 to disable line wrapping.
(default: 100)
```
## Whitelisting star imports
`removestar` does not replace star import lines that are marked with
[Flake8 `noqa` comments][noqa-comments] that permit star imports (`F401` or
`F403`).
[noqa-comments]: https://flake8.pycqa.org/en/3.1.1/user/ignoring-errors.html#in-line-ignoring-errors
For example, the star imports in this module would be kept:
```py
from os import * # noqa: F401
from .b import * # noqa
def func(x):
return x + y
```
## Current limitations
- Assumes only names in the current file are used by star imports (e.g., it
won't work to replace star imports in `__init__.py`).
- For files within the same module, removestar determines missing imported names
statically. For external library imports, including imports of standard
library modules, it dynamically imports the module to determine the names.
This can be disabled with the `--no-dynamic-importing` flag.
## Contributing
See the [issue tracker](https://github.com/asmeurer/removestar/issues). Pull
requests are welcome.
## Changelog
See the [CHANGELOG](CHANGELOG.md) file.
## License
[MIT](LICENSE)
[actions-badge]: https://github.com/asmeurer/removestar/workflows/CI/badge.svg
[actions-link]: https://github.com/asmeurer/removestar/actions
[codecov-badge]: https://codecov.io/gh/asmeurer/removestar/branch/main/graph/badge.svg?token=YBv60ueORQ
[codecov-link]: https://codecov.io/gh/asmeurer/removestar
[conda-downloads]: https://img.shields.io/conda/dn/conda-forge/removestar?color=green
[conda-link]: https://anaconda.org/conda-forge/removestar
[conda-version]: https://anaconda.org/conda-forge/removestar/badges/version.svg
[github-discussions-badge]: https://img.shields.io/static/v1?label=Discussions&message=Ask&color=blue&logo=github
[github-discussions-link]: https://github.com/asmeurer/removestar/discussions
[license-badge]: https://img.shields.io/badge/MIT-blue.svg
[license-link]: https://opensource.org/licenses/MIT
[pypi-downloads]: https://static.pepy.tech/badge/removestar
[pre-commit-badge]: https://results.pre-commit.ci/badge/github/asmeurer/removestar/develop.svg
[pre-commit-link]: https://results.pre-commit.ci/repo/github/asmeurer/removestar
[pypi-link]: https://pypi.org/project/removestar/
[pypi-platforms]: https://img.shields.io/pypi/pyversions/removestar
[pypi-version]: https://img.shields.io/pypi/v/removestar?color=blue
[ruff-badge]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
[ruff-link]: https://github.com/astral-sh/ruff
Raw data
{
"_id": null,
"home_page": null,
"name": "removestar",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "Aaron Meurer <asmeurer@gmail.com>, Saransh Chopra <saransh0701@gmail.com>",
"keywords": null,
"author": null,
"author_email": "Aaron Meurer <asmeurer@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/ec/74/9c7573b4f920ace695459bc202e2ccb6ef4f595c36b1847a7a0bd1488245/removestar-1.5.2.tar.gz",
"platform": null,
"description": "# removestar\n\n[![Actions Status][actions-badge]][actions-link]\n[![PyPI version][pypi-version]][pypi-link]\n[![Anaconda-Server Badge][conda-version]][conda-link]\n[![PyPI platforms][pypi-platforms]][pypi-link]\n[![Downloads][pypi-downloads]][pypi-link]\n[![Conda Downloads][conda-downloads]][conda-link]\n[![Ruff][ruff-badge]][ruff-link]\n\n<!-- TODO:\n[![pre-commit.ci status][pre-commit-badge]][pre-commit-link]\n[![codecov percentage][codecov-badge]][codecov-link]\n[![GitHub Discussion][github-discussions-badge]][github-discussions-link]\n-->\n\nTool to automatically replace `import *` imports in Python files with explicit imports\n\n## Installation\n\nInstall `removestar` globally to use it through CLI using `pypi` -\n\n```bash\npip install removestar\npip install \"removestar[nb]\" # notebook support\n```\n\nor `conda` -\n\n```bash\nconda install -c conda-forge removestar\n```\n\nor add `removestar` in `.pre-commit-config.yaml` -\n\n```yaml\n- repo: https://github.com/asmeurer/removestar\n rev: \"1.5\"\n hooks:\n - id: removestar\n args: [-i] # See docs for all args (-i edits file in-place)\n additional_dependencies: # The libraries or packages your code imports\n - ... # Add . if running inside a library (to install the library itself in the environment)\n - ... # Add nbformat and nbconvert for notebook support\n```\n\n## Usage\n\n### pre-commit hook\n\nOnce `removestar` is added in `.pre-commit-config.yaml`, executing the following\nwill always run it (and other pre-commits) before every commit -\n\n```bash\npre-commit install\n```\n\nOptionally, the pre-commits (including `removestar`) can be manually triggered for\nall the files using -\n\n```bash\npre-commit run --all-files\n```\n\n### CLI\n\n```bash\n\n# scripts\n\n$ removestar file.py # Shows diff but does not edit file.py\n\n$ removestar -i file.py # Edits file.py in-place\n\n$ removestar -i module/ # Modifies every Python file in module/ recursively\n\n# notebooks (make sure nbformat and nbconvert are installed)\n\n$ removestar file.ipynb # Shows diff but does not edit file.ipynb\n\n$ removestar -i file.ipynb # Edits file.ipynb in-place\n```\n\n## Why is `import *` so bad?\n\nDoing `from module import *` is generally frowned upon in Python. It is\nconsidered acceptable when working interactively at a `python` prompt, or in\n`__init__.py` files (removestar skips `__init__.py` files by default).\n\nSome reasons why `import *` is bad:\n\n- It hides which names are actually imported.\n- It is difficult both for human readers and static analyzers such as\n pyflakes to tell where a given name comes from when `import *` is used. For\n example, pyflakes cannot detect unused names (for instance, from typos) in\n the presence of `import *`.\n- If there are multiple `import *` statements, it may not be clear which names\n come from which module. In some cases, both modules may have a given name,\n but only the second import will end up being used. This can break people's\n intuition that the order of imports in a Python file generally does not\n matter.\n- `import *` often imports more names than you would expect. Unless the module\n you import defines `__all__` or carefully `del`s unused names at the module\n level, `import *` will import every public (doesn't start with an\n underscore) name defined in the module file. This can often include things\n like standard library imports or loop variables defined at the top-level of\n the file. For imports from modules (from `__init__.py`), `from module import\n*` will include every submodule defined in that module. Using `__all__` in\n modules and `__init__.py` files is also good practice, as these things are\n also often confusing even for interactive use where `import *` is\n acceptable.\n- In Python 3, `import *` is syntactically not allowed inside of a function.\n\nHere are some official Python references stating not to use `import *` in\nfiles:\n\n- [The official Python\n FAQ](https://docs.python.org/3/faq/programming.html?highlight=faq#what-are-the-best-practices-for-using-import-in-a-module):\n\n > In general, don\u2019t use `from modulename import *`. Doing so clutters the\n > importer\u2019s namespace, and makes it much harder for linters to detect\n > undefined names.\n\n- [PEP 8](https://www.python.org/dev/peps/pep-0008/#imports) (the official\n Python style guide):\n\n > Wildcard imports (`from <module> import *`) should be avoided, as they\n > make it unclear which names are present in the namespace, confusing both\n > readers and many automated tools.\n\nUnfortunately, if you come across a file in the wild that uses `import *`, it\ncan be hard to fix it, because you need to find every name in the file that is\nimported from the `*`. Removestar makes this easy by finding which names come\nfrom `*` imports and replacing the import lines in the file automatically.\n\nOne exception where `import *` can be bneficial:\nAt the early stages of code development, a definite set of required\nfunctions can be difficult to determine. In such a context, wildcard imports could be\nbeneficial by avoiding constantly curating the set of required functions. For example,\nat the development stage usage of `from os.path import *` can save time from curating\nrequired functions. Post-development, the wld card imports could be determined using\n`removestar`. Having said that, because of the multiple said reasons, wildcard imports\nshould be avoided.\n\n## Example\n\nSuppose you have a module `mymod` like\n\n```bash\nmymod/\n | __init__.py\n | a.py\n | b.py\n```\n\nWith\n\n```py\n# mymod/a.py\nfrom .b import *\n\n\ndef func(x):\n return x + y\n```\n\n```py\n# mymod/b.py\nx = 1\ny = 2\n```\n\nThen `removestar` works like:\n\n```bash\n$ removestar mymod/\n\n--- original/mymod/a.py\n+++ fixed/mymod/a.py\n@@ -1,5 +1,5 @@\n # mymod/a.py\n-from .b import *\n+from .b import y\n\n def func(x):\n return x + y\n\n```\n\nThis does not edit `a.py` by default. The `-i` flag causes it to edit `a.py` in-place:\n\n```bash\n$ removestar -i mymod/\n$ cat mymod/a.py\n# mymod/a.py\nfrom .b import y\n\ndef func(x):\n return x + y\n```\n\n## Command line options\n\n<!-- TODO: Autogenerate this somehow -->\n\n```bash\n$ removestar --help\nusage: removestar [-h] [-i] [--version] [--no-skip-init]\n [--no-dynamic-importing] [-v] [-q]\n [--max-line-length MAX_LINE_LENGTH]\n PATH [PATH ...]\n\nTool to automatically replace \"import *\" imports with explicit imports\n\nRequires pyflakes.\n\nUsage:\n\n$ removestar file.py # Shows diff but does not edit file.py\n\n$ removestar -i file.py # Edits file.py in-place\n\n$ removestar -i module/ # Modifies every Python file in module/ recursively\n\npositional arguments:\n PATH Files or directories to fix\n\noptional arguments:\n -h, --help show this help message and exit\n -i, --in-place Edit the files in-place. (default: False)\n --version Show removestar version number and exit.\n --no-skip-init Don't skip __init__.py files (they are skipped by\n default) (default: True)\n --no-dynamic-importing\n Don't dynamically import modules to determine the list\n of names. This is required for star imports from\n external modules and modules in the standard library.\n (default: True)\n -v, --verbose Print information about every imported name that is\n replaced. (default: False)\n -q, --quiet Don't print any warning messages. (default: False)\n --max-line-length MAX_LINE_LENGTH\n The maximum line length for replaced imports before\n they are wrapped. Set to 0 to disable line wrapping.\n (default: 100)\n```\n\n## Whitelisting star imports\n\n`removestar` does not replace star import lines that are marked with\n[Flake8 `noqa` comments][noqa-comments] that permit star imports (`F401` or\n`F403`).\n\n[noqa-comments]: https://flake8.pycqa.org/en/3.1.1/user/ignoring-errors.html#in-line-ignoring-errors\n\nFor example, the star imports in this module would be kept:\n\n```py\nfrom os import * # noqa: F401\nfrom .b import * # noqa\n\n\ndef func(x):\n return x + y\n```\n\n## Current limitations\n\n- Assumes only names in the current file are used by star imports (e.g., it\n won't work to replace star imports in `__init__.py`).\n\n- For files within the same module, removestar determines missing imported names\n statically. For external library imports, including imports of standard\n library modules, it dynamically imports the module to determine the names.\n This can be disabled with the `--no-dynamic-importing` flag.\n\n## Contributing\n\nSee the [issue tracker](https://github.com/asmeurer/removestar/issues). Pull\nrequests are welcome.\n\n## Changelog\n\nSee the [CHANGELOG](CHANGELOG.md) file.\n\n## License\n\n[MIT](LICENSE)\n\n[actions-badge]: https://github.com/asmeurer/removestar/workflows/CI/badge.svg\n[actions-link]: https://github.com/asmeurer/removestar/actions\n[codecov-badge]: https://codecov.io/gh/asmeurer/removestar/branch/main/graph/badge.svg?token=YBv60ueORQ\n[codecov-link]: https://codecov.io/gh/asmeurer/removestar\n[conda-downloads]: https://img.shields.io/conda/dn/conda-forge/removestar?color=green\n[conda-link]: https://anaconda.org/conda-forge/removestar\n[conda-version]: https://anaconda.org/conda-forge/removestar/badges/version.svg\n[github-discussions-badge]: https://img.shields.io/static/v1?label=Discussions&message=Ask&color=blue&logo=github\n[github-discussions-link]: https://github.com/asmeurer/removestar/discussions\n[license-badge]: https://img.shields.io/badge/MIT-blue.svg\n[license-link]: https://opensource.org/licenses/MIT\n[pypi-downloads]: https://static.pepy.tech/badge/removestar\n[pre-commit-badge]: https://results.pre-commit.ci/badge/github/asmeurer/removestar/develop.svg\n[pre-commit-link]: https://results.pre-commit.ci/repo/github/asmeurer/removestar\n[pypi-link]: https://pypi.org/project/removestar/\n[pypi-platforms]: https://img.shields.io/pypi/pyversions/removestar\n[pypi-version]: https://img.shields.io/pypi/v/removestar?color=blue\n[ruff-badge]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json\n[ruff-link]: https://github.com/astral-sh/ruff\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A tool to automatically replace 'import *' imports with explicit imports in files",
"version": "1.5.2",
"project_urls": {
"Bug Tracker": "https://github.com/asmeurer/removestar/issues",
"Homepage": "https://www.asmeurer.com/removestar/",
"Source Code": "https://github.com/asmeurer/removestar"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d73153be571cb0fce757a1ba2bbb11541fceceb0a1852a16741e9e3947c3db1b",
"md5": "207d4b1bd4d3eab0d3e18d22018f1744",
"sha256": "774278462d8d9d8c27ae92b12e9882bffddf3cba67da317a97508653ed12df86"
},
"downloads": -1,
"filename": "removestar-1.5.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "207d4b1bd4d3eab0d3e18d22018f1744",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 16150,
"upload_time": "2024-11-25T15:38:23",
"upload_time_iso_8601": "2024-11-25T15:38:23.775760Z",
"url": "https://files.pythonhosted.org/packages/d7/31/53be571cb0fce757a1ba2bbb11541fceceb0a1852a16741e9e3947c3db1b/removestar-1.5.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ec749c7573b4f920ace695459bc202e2ccb6ef4f595c36b1847a7a0bd1488245",
"md5": "ba47063afc5da6f931a4fcbf0b2e7cf3",
"sha256": "282d6dcb908a12b6dbf9c1050a04256f160e2de2c8bdea78a443dd547486fe3b"
},
"downloads": -1,
"filename": "removestar-1.5.2.tar.gz",
"has_sig": false,
"md5_digest": "ba47063afc5da6f931a4fcbf0b2e7cf3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 13988,
"upload_time": "2024-11-25T15:38:25",
"upload_time_iso_8601": "2024-11-25T15:38:25.103189Z",
"url": "https://files.pythonhosted.org/packages/ec/74/9c7573b4f920ace695459bc202e2ccb6ef4f595c36b1847a7a0bd1488245/removestar-1.5.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-25 15:38:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "asmeurer",
"github_project": "removestar",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "removestar"
}
