Metadata-Version: 2.1
Name: modguard
Version: 0.0.1
Summary: A Python tool to guard against incorrect usage of python modules.
Author: Caelean Barnes & Evan Doyle
Author-email: Caelean Barnes <caeleanb@gmail.com>, Evan Doyle <evanmdoyle@gmail.com>
Project-URL: Homepage, https://github.com/never-over/modguard
Project-URL: Issues, https://github.com/never-over/modguard/issues
Keywords: python,module,guard,enforcement,enforcer,decorator,subclass
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 4 - Beta
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE

# modguard
---
A Python tool to guard against incorrect usage of python modules.


### What is modguard?
Modguard enables you to wrap Python functions, classes, and modules to prevent unintended usage across your codebase.

This helps prevent other developers unintentionally mis-using code, which can lead to poor performance, security vulnerabilities, bugs, and more.

Modguard is incredibly lightweight, and has no impact on the runtime of your code. Instead, it's checks are performed through a lightweight CLI tool.

### Installation
```bash
pip install modguard
```
[PyPi](#TODO)

### Usage
Implement the `guard` decorator and specify either the `allow` or `deny` parameter.
```python
# core/utils.py

@guard(deny=['core.utils, public.api'])
def retrieve_password(user_id: int) -> str:
    ...

def some_util():
    ...
    retrieve_password()
    ...
```
```bash
> # From the root of your project
> guard .
1 error found.
core/utils.py:L45-60 E001 Restricted usage of 'retrieve_password'
```
Modguard works across imports within the scope of your project
```
# public/api.py

from core.utils import retrieve_password

def some_api():
    ...
    retrieve_password()
    ...
```
```bash
> # From the root of your project
> modguard .
2 errors found.
core/utils.py:L45-60 E001 Restricted usage of 'retrieve_password' in 'core.utils.some_util'
public/api.py:L45-60 E001 Restricted usage of 'retrieve_password' in 'public.api.some_api'
```

### Interface
```python
"""Decorator for protecting against unintended usage. Note that you may only specify `allow` or `deny`, but not both.
Parameters:
    allow (Iterable[str]): A list of str representations of python module paths that are allowed to implement the decorated object.

    deny (Iterable[str]): A list of str representations of python module paths that are not allowed to implement the decorated object 

Return:
    None
"""
@guard(allow: Iterable[str]= [], deny: Iterable[str])
...
```




### Examples



### Details
Modguard works by analyzing the abstract syntax tree of your codebase. It will only protect against usages that are within the scope of the cli runtime, which is why we suggest always running the tool from the root of your project.

### License
[GNU GPLv3](LICENSE)
