Metadata-Version: 2.4
Name: neutralise_link
Version: 0.1.3
Summary: Validating, cleaning, and compactifying URLs simplified.
Project-URL: Homepage, https://github.com/brainpolo/neutralise-link
Project-URL: Bug Tracker, https://github.com/brainpolo/neutralise-link/issues
Author-email: Aditya Dedhia <aditya@brainpolo.com>
License-File: LICENSE
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# neturalise-link

## What are the objectives?

- Remove trackers
- Remove referrers
- Identify malicious intent
- Verify URL validity
- Improve URL load speeds

## How does it work?

Having imported `neutralise-link` you may use the `neutralise` function which takes a URL string as the argument.

The function is designed to return either a string URL or None. It is recommended to
use the returned URL value in place of the original URL as this is the neutralised
version of the URL.

By default, the function will return `None` in two cases:

1. The link is invalid
2. The link is deemed malicious

> You may override the 2nd case by calling the function with the optional parameter, `safe=false`.

> You may also skip the validity check by calling the function with the optional parameter, `check_valid=false`. This is recommended if you do not need to check for URL validity as it leads to significantly faster performance, but at the potential risk of returning impure URLs (i.e. URLs that have been redirected).

## Example Code

```python
from neutralise_link import neutralise

def main(url: str) -> str:
    """Validate user URL input for storing."""

    url = neutralise(url=url, safe=True, check_valid=True)
    if not url:
        print("URL is malformed or malicious.")
    print("URL is safe and in its pure form.")
```

## Contributing

### Prerequisites

- Have python 3.10 installed on system (e.g. using anaconda/homebrew)

### Environment Setup

1. Set up a virtual environment using `python -m venv venv`
2. Activate the virtual environment using `source venv/bin/activate`
3. Install development dependencies using `pip install -r requirements.txt`

### Running tests

It is important to ensure that ALL tests pass before submitting a PR.

```bash
python -m unittest discover -s tests
```

It is also imperative that coverage is above 90% before submitting a PR. Validate this by running:

```bash
coverage run -m tests.test_neutralise && coverage report && coverage html
```

### Building the package

1. Navigate to root directory of the project and run: `python -m build`

2. Install the package found in `neutralise-link/dist/`
   in your repo using `pip install` followed by the relative path of the `.tar.gz` package file located in the project. For example:

```bash
pip install dist/neutralise_link-0.1.0.tar.gz
```

### Uploading to PyPI

Ensure that the package is built and the dist directory is populated. Then run:

```bash
python -m twine upload dist/*
```
