| Name | witchery JSON |
| Version |
0.2.0
JSON |
| download |
| home_page | None |
| Summary | Witchery is a powerful Python library that offers various functionalities for code analysis and modification. |
| upload_time | 2023-11-17 16:35:46 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | None |
| keywords |
databases
pydal
sql
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Witchery
**A Python Package for Code Analysis and Modification**
Witchery is a powerful Python library that offers various functionalities for code analysis and modification. It
provides tools to traverse Abstract Syntax Trees (AST) of Python code and perform tasks such as finding defined
variables, removing specific variables, identifying local imports, adding function calls, and much more.
Whether you need to analyze code for missing variables, remove certain variables from your codebase, or perform code
transformations, Witchery has you covered. It is a versatile utility for developers and programmers seeking to enhance
their code analysis and modification capabilities.
With Witchery, you can easily parse Python code, identify used and defined variables, handle imports, and generate code
for missing variables, among other useful features. This package is designed to simplify code manipulation tasks and
assist in creating cleaner and more efficient Python codebases.
Features:
- Find defined variables within Python code
- Remove specific variables from code
- Identify local imports in code
- Remove imports of specific modules
- Add function calls to existing code
- Find missing variables in code
- Generate ✨ magic ✨ code to define missing variables
- and more!
[](https://pypi.org/project/witchery)
[](https://pypi.org/project/witchery)
[](https://github.com/psf/black)
[](https://opensource.org/licenses/MIT)
[](https://github.com/robinvandernoord/witchery/actions)
-----
## Table of Contents
- [Installation](#installation)
- [Usage](#usage)
- [Examples](#examples)
- [License](#license)
## Installation
You can install `witchery` using pip:
```bash
pip install witchery
```
## Usage
The `witchery` library provides several useful methods to work with Python code. Here are the main functions and their
purposes:
1. `find_defined_variables(code_str: str) -> set[str]`: Parses the given Python code and finds all variables that are
defined within. It returns a set of variable names that are defined in the provided Python code.
2. `remove_specific_variables(code: str, to_remove: typing.Iterable[str] = ("db", "database")) -> str`: Removes specific
variables from the given code. You can specify a list of variable names to be removed, and the function will return
the code after removing the specified variables.
3. `has_local_imports(code: str) -> bool`: Checks if the given code has local imports. It returns True if local imports
are found, and False otherwise.
4. `remove_import(code: str, module_name: typing.Optional[str]) -> str`: Removes the import of a specific module from
the given code. You can specify the name of the module to remove, and the function will return the code after
removing the import of the specified module.
5. `remove_local_imports(code: str) -> str`: Removes all local imports from the given code. It returns the code after
removing all local imports.
6. `find_function_to_call(code: str, function_call_hint: str) -> typing.Optional[str]`: Finds the function to call in
the given code based on the function call hint. It returns the name of the function to call if found, or None
otherwise.
7. `extract_function_details(function_call: str, default_args: typing.Iterable[str] = DEFAULT_ARGS) -> tuple[str | None, list[str]]`:
Extracts the function name and arguments from the function call string. It returns a tuple containing the function
name and a list of arguments.
8. `add_function_call(code: str, function_call: str, args: typing.Iterable[str] = DEFAULT_ARGS) -> str`: Adds a function
call to the given code. You can specify the function call string and the arguments for the function call.
9. `find_variables(code_str: str) -> tuple[set[str], set[str]]`: Finds all used and defined variables in the given code
string. It returns a tuple containing sets of used and defined variables.
10. `find_missing_variables(code: str) -> set[str]`: Finds and returns all missing variables in the given code. It
returns a set of names of missing variables.
11. `generate_magic_code(missing_vars: set[str]) -> str`: Generates code to define missing variables with a do-nothing
object. After finding missing variables, it fills them in with an object that does nothing except return itself or
an empty string.
## Examples
```python
import witchery
# Example 1: Find defined variables in code
code = """
x = 5
y = 10
z = x + y
"""
defined_vars = witchery.find_defined_variables(code)
print(defined_vars)
# Output: {'x', 'y', 'z'}
# Example 2: Remove specific variables from code
code = """
x = 5
y = 10
db = Database()
"""
new_code = witchery.remove_specific_variables(code, to_remove=["x", "db"])
print(new_code)
# Output: "y = 10"
# Example 3: Check if code has local imports
code = "from my_module import my_function"
has_local_imports = witchery.has_local_imports(code)
print(has_local_imports)
# Output: False
code = "from .my_module import my_function"
has_local_imports = witchery.has_local_imports(code)
print(has_local_imports)
# Output: True
# Example 4: Remove import of a specific module from code
code = """
import module_name
from module_name import something
x = module_name.function()
"""
new_code = witchery.remove_import(code, module_name="module_name")
print(new_code)
# Output: "x = module_name.function()"
# do note that this only removes the import, NOT any function calls to it!
# Example 5: Remove all local imports from code
code = """
from .local_module import something
from another_module import func
def my_function():
return func(), something()
"""
new_code = witchery.remove_local_imports(code)
print(new_code)
# Output:
# from another_module import func
#
# def my_function():
# return func(), something()
# do note that this only removes the imports, NOT any function calls to it!
# Example 6: Find the function to call based on the function call hint
code = """
def my_function():
return 42
x = my_function()
"""
function_to_call = witchery.find_function_to_call(code, "my_function()") # can be with or without parentheses
print(function_to_call)
# Output: "my_function"
# will be None if the function does not exist in the specified code.
# Example 7: Extract function name and arguments from function call string
function_call = "my_function(x, y, 'z')"
function_name, args = witchery.extract_function_details(function_call)
print(function_name)
# Output: "my_function"
print(args)
# Output: ['x', 'y', "'z'"]
# Example 8: Add a function call to code
code = """
def add(a, b):
return a + b
result = add(3, 5)
"""
new_code = witchery.add_function_call(code, function_call="add(x, y)")
print(new_code)
# Output:
# def add(a, b):
# return a + b
# add(x, y)
# result = add(3, 5)
# The call will be placed right below the function definition.
# Example 9: Find used and defined variables in code
code = """
x = 5
y = x + z
result = x * y
"""
used_vars, defined_vars = witchery.find_variables(code, with_builtins=False)
print(used_vars)
# Output: {'x', 'y', 'z'}
print(defined_vars)
# Output: {'x', 'y', 'result'} # will be a lot longer if with_builtins = True
# Example 10: Find missing variables in code
code = """
x = 5
result = x * y
"""
missing_vars = witchery.find_missing_variables(code)
print(missing_vars)
# Output: {'y'}
# Example 11: Generate magic code to define missing variables
missing_vars = {'y', 'z'}
magic_code = witchery.generate_magic_code(missing_vars)
print(magic_code)
# Output: """
# class Empty:
# ...
#
# empty = Empty()
# y = empty; z = empty;
# """
```
## License
`witchery` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.
Raw data
{
"_id": null,
"home_page": null,
"name": "witchery",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "databases,pydal,sql",
"author": null,
"author_email": "Robin van der Noord <robinvandernoord@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/dd/ed/273913151edf2de4b7ffe2febaaf15d15c1836592bac2de41eee9709b36c/witchery-0.2.0.tar.gz",
"platform": null,
"description": "# Witchery\n\n**A Python Package for Code Analysis and Modification**\n\nWitchery is a powerful Python library that offers various functionalities for code analysis and modification. It\nprovides tools to traverse Abstract Syntax Trees (AST) of Python code and perform tasks such as finding defined\nvariables, removing specific variables, identifying local imports, adding function calls, and much more.\n\nWhether you need to analyze code for missing variables, remove certain variables from your codebase, or perform code\ntransformations, Witchery has you covered. It is a versatile utility for developers and programmers seeking to enhance\ntheir code analysis and modification capabilities.\n\nWith Witchery, you can easily parse Python code, identify used and defined variables, handle imports, and generate code\nfor missing variables, among other useful features. This package is designed to simplify code manipulation tasks and\nassist in creating cleaner and more efficient Python codebases.\n\nFeatures:\n\n- Find defined variables within Python code\n- Remove specific variables from code\n- Identify local imports in code\n- Remove imports of specific modules\n- Add function calls to existing code\n- Find missing variables in code\n- Generate \u2728 magic \u2728 code to define missing variables\n- and more!\n\n[](https://pypi.org/project/witchery)\n[](https://pypi.org/project/witchery) \n[](https://github.com/psf/black)\n[](https://opensource.org/licenses/MIT) \n[](https://github.com/robinvandernoord/witchery/actions)\n\n\n-----\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Usage](#usage)\n- [Examples](#examples)\n- [License](#license)\n\n## Installation\n\nYou can install `witchery` using pip:\n\n```bash\npip install witchery\n```\n\n## Usage\n\nThe `witchery` library provides several useful methods to work with Python code. Here are the main functions and their\npurposes:\n\n1. `find_defined_variables(code_str: str) -> set[str]`: Parses the given Python code and finds all variables that are\n defined within. It returns a set of variable names that are defined in the provided Python code.\n\n2. `remove_specific_variables(code: str, to_remove: typing.Iterable[str] = (\"db\", \"database\")) -> str`: Removes specific\n variables from the given code. You can specify a list of variable names to be removed, and the function will return\n the code after removing the specified variables.\n\n3. `has_local_imports(code: str) -> bool`: Checks if the given code has local imports. It returns True if local imports\n are found, and False otherwise.\n\n4. `remove_import(code: str, module_name: typing.Optional[str]) -> str`: Removes the import of a specific module from\n the given code. You can specify the name of the module to remove, and the function will return the code after\n removing the import of the specified module.\n\n5. `remove_local_imports(code: str) -> str`: Removes all local imports from the given code. It returns the code after\n removing all local imports.\n\n6. `find_function_to_call(code: str, function_call_hint: str) -> typing.Optional[str]`: Finds the function to call in\n the given code based on the function call hint. It returns the name of the function to call if found, or None\n otherwise.\n\n7. `extract_function_details(function_call: str, default_args: typing.Iterable[str] = DEFAULT_ARGS) -> tuple[str | None, list[str]]`:\n Extracts the function name and arguments from the function call string. It returns a tuple containing the function\n name and a list of arguments.\n\n8. `add_function_call(code: str, function_call: str, args: typing.Iterable[str] = DEFAULT_ARGS) -> str`: Adds a function\n call to the given code. You can specify the function call string and the arguments for the function call.\n\n9. `find_variables(code_str: str) -> tuple[set[str], set[str]]`: Finds all used and defined variables in the given code\n string. It returns a tuple containing sets of used and defined variables.\n\n10. `find_missing_variables(code: str) -> set[str]`: Finds and returns all missing variables in the given code. It\n returns a set of names of missing variables.\n\n11. `generate_magic_code(missing_vars: set[str]) -> str`: Generates code to define missing variables with a do-nothing\n object. After finding missing variables, it fills them in with an object that does nothing except return itself or\n an empty string.\n\n## Examples\n\n```python\nimport witchery\n\n# Example 1: Find defined variables in code\ncode = \"\"\"\nx = 5\ny = 10\nz = x + y\n\"\"\"\ndefined_vars = witchery.find_defined_variables(code)\nprint(defined_vars)\n# Output: {'x', 'y', 'z'}\n\n# Example 2: Remove specific variables from code\ncode = \"\"\"\nx = 5\ny = 10\ndb = Database()\n\"\"\"\nnew_code = witchery.remove_specific_variables(code, to_remove=[\"x\", \"db\"])\nprint(new_code)\n# Output: \"y = 10\"\n\n# Example 3: Check if code has local imports\ncode = \"from my_module import my_function\"\nhas_local_imports = witchery.has_local_imports(code)\nprint(has_local_imports)\n# Output: False\n\ncode = \"from .my_module import my_function\"\nhas_local_imports = witchery.has_local_imports(code)\nprint(has_local_imports)\n# Output: True\n\n# Example 4: Remove import of a specific module from code\ncode = \"\"\"\nimport module_name\nfrom module_name import something\nx = module_name.function()\n\"\"\"\nnew_code = witchery.remove_import(code, module_name=\"module_name\")\nprint(new_code)\n# Output: \"x = module_name.function()\"\n\n# do note that this only removes the import, NOT any function calls to it!\n\n# Example 5: Remove all local imports from code\ncode = \"\"\"\nfrom .local_module import something\nfrom another_module import func\n\ndef my_function():\n return func(), something()\n\"\"\"\nnew_code = witchery.remove_local_imports(code)\nprint(new_code)\n# Output:\n# from another_module import func\n# \n# def my_function():\n# return func(), something()\n\n# do note that this only removes the imports, NOT any function calls to it!\n\n# Example 6: Find the function to call based on the function call hint\ncode = \"\"\"\ndef my_function():\n return 42\n\nx = my_function()\n\"\"\"\nfunction_to_call = witchery.find_function_to_call(code, \"my_function()\") # can be with or without parentheses\nprint(function_to_call)\n# Output: \"my_function\"\n\n# will be None if the function does not exist in the specified code.\n\n# Example 7: Extract function name and arguments from function call string\nfunction_call = \"my_function(x, y, 'z')\"\nfunction_name, args = witchery.extract_function_details(function_call)\nprint(function_name)\n# Output: \"my_function\"\nprint(args)\n# Output: ['x', 'y', \"'z'\"]\n\n# Example 8: Add a function call to code\ncode = \"\"\"\ndef add(a, b):\n return a + b\n\nresult = add(3, 5)\n\"\"\"\nnew_code = witchery.add_function_call(code, function_call=\"add(x, y)\")\nprint(new_code)\n# Output: \n# def add(a, b):\n# return a + b\n# add(x, y)\n# result = add(3, 5)\n\n# The call will be placed right below the function definition.\n\n# Example 9: Find used and defined variables in code\ncode = \"\"\"\nx = 5\ny = x + z\nresult = x * y\n\"\"\"\nused_vars, defined_vars = witchery.find_variables(code, with_builtins=False)\nprint(used_vars)\n# Output: {'x', 'y', 'z'}\nprint(defined_vars)\n# Output: {'x', 'y', 'result'} # will be a lot longer if with_builtins = True\n\n# Example 10: Find missing variables in code\ncode = \"\"\"\nx = 5\nresult = x * y\n\"\"\"\nmissing_vars = witchery.find_missing_variables(code)\nprint(missing_vars)\n# Output: {'y'}\n\n# Example 11: Generate magic code to define missing variables\nmissing_vars = {'y', 'z'}\nmagic_code = witchery.generate_magic_code(missing_vars)\nprint(magic_code)\n# Output: \"\"\"\n# class Empty:\n# ...\n#\n# empty = Empty()\n# y = empty; z = empty;\n# \"\"\"\n\n```\n\n## License\n\n`witchery` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.\n",
"bugtrack_url": null,
"license": null,
"summary": "Witchery is a powerful Python library that offers various functionalities for code analysis and modification.",
"version": "0.2.0",
"project_urls": {
"Documentation": "https://github.com/robinvandernoord/witchery#readme",
"Issues": "https://github.com/robinvandernoord/witchery/issues",
"Source": "https://github.com/robinvandernoord/witchery"
},
"split_keywords": [
"databases",
"pydal",
"sql"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "dcf0a84af7b915fe91dc1081b788550bfb5bb00d8b73fe9e4298ac2ef7989308",
"md5": "e6283ae99d08c9bbd9eb7ce746acb765",
"sha256": "40fcc60b22005b063ac7f86e4441816a91c45cc1ed01f31187c8677d92680f8f"
},
"downloads": -1,
"filename": "witchery-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e6283ae99d08c9bbd9eb7ce746acb765",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 10023,
"upload_time": "2023-11-17T16:35:44",
"upload_time_iso_8601": "2023-11-17T16:35:44.190526Z",
"url": "https://files.pythonhosted.org/packages/dc/f0/a84af7b915fe91dc1081b788550bfb5bb00d8b73fe9e4298ac2ef7989308/witchery-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "dded273913151edf2de4b7ffe2febaaf15d15c1836592bac2de41eee9709b36c",
"md5": "0402d9753fb10931278b644448105583",
"sha256": "93583c6c3a72d93eb352ce9d6ab42a36aae880507477ddc5dc931a5c2af7a328"
},
"downloads": -1,
"filename": "witchery-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "0402d9753fb10931278b644448105583",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 51308,
"upload_time": "2023-11-17T16:35:46",
"upload_time_iso_8601": "2023-11-17T16:35:46.707112Z",
"url": "https://files.pythonhosted.org/packages/dd/ed/273913151edf2de4b7ffe2febaaf15d15c1836592bac2de41eee9709b36c/witchery-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-17 16:35:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "robinvandernoord",
"github_project": "witchery#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "witchery"
}
