SauceNAO

unofficial python module to make working with SauceNAO in projects easier

Installation

This package requires Python 3.6 or later.

You can simply install the latest version with

pip install SauceNAO

Alternatively you can download this repository and run the setup.py to install all necessary dependencies. In case you want to install the dependencies to run the unit tests you can additionally run pip install -e .[dev] in this project.

Dependencies

Required:

BeautifulSoup - html parser
requests - http library

Optional:

Pillow - Python Imaging Library, used to generate images for unittests
python-dotenv - .env file loader used for unittests
requests-mock - requests mock responses used for unittests

Usage

You can run SauceNAO either as module:

import logging

from saucenao import SauceNao, SauceNaoDatabase

saucenao = SauceNao(directory='directory', databases=SauceNaoDatabase.All, minimum_similarity=65,
                    combine_api_types=False, api_key='', is_premium=False, exclude_categories='',
                    move_to_categories=False, use_author_as_category=False, output_type=SauceNao.API_HTML_TYPE,
                    start_file='', log_level=logging.ERROR, title_minimum_similarity=90)

or as application:

python usage.py --dir [--databases] [--minimum-similarity] [--combine-api-types] [--api-key] [--premium]
                [--exclude-categories] [--move-to-categories] [--use-author-as-category] [--output-type] [--start-file]
                [--log-level] [--filter-creation-date] [--filter-modified-date] [--title-minimum-similarity]

you can also use it to get the gathered information for your own script:

# check with file names
filtered_results = saucenao.check_file(file_name='test.jpg')
# or with streams/byte objects
filtered_results = saucenao.check_file_object(io.BytesIO(b'\x00'))

or get a generator object for a bulk of files using the worker class, all parameters work here too:

from saucenao import Worker

results = Worker(directory='directory', files=('test.jpg', 'test2.jpg', io.BytesIO(b'\x00'))).run()

the worker automatically differentiates between file names and BinaryIO objects, so you can simply pass both types at the same time.

Running the tests

In the tests folder you can run each unittest individually.
The test cases should be self-explanatory.

Development

Want to contribute? Great!
I'm always glad hearing about bugs or pull requests.

License

This project is licensed under the MIT License - see the LICENSE.md file for details

Thanks

A big thanks to SauceNAO who are indexing all the images and compares them.
This script would be completely useless without them.

DaRealFreak / saucenao