Skip to main content

pySauceNao is an unofficial library for the SauceNao API.

Project description

pySauceNao

pySauceNao is an unofficial asynchronous library for the SauceNao API. It supports lookups via remote URL's or uploads from the local filesystem.

Installation

This library requires Python 3.11 or above.

You can install the library through pip as follows,

pip install pysaucenao

Basic usage

Make sure you have obtained an API key from SauceNao first.

The following example demonstrates how to use the library to perform a lookup on a remote image file,

import asyncio
from pysaucenao import SauceNao

sauce = SauceNao(api_key='your_api_key')
results = asyncio.run(sauce.from_url('https://m.media-amazon.com/images/S/pv-target-images/4e34528d6934e91a4ab5120af64ba86ca0315eec83fc68e63b376b15aa136c10.png'))
for result in results:
    print(f"Title: {result.title} ({result.similarity}% match)")
    print(f"Author: {result.author_name}")
    print(f"Link: {result.url}\n")

Some search results, such as anime search results, can contain additional information such as episode numbers, timestamps and so on.

import asyncio
from pysaucenao import SauceNao, AnimeSource

sauce = SauceNao(api_key='your_api_key')
results = asyncio.run(sauce.from_url('https://m.media-amazon.com/images/S/pv-target-images/4e34528d6934e91a4ab5120af64ba86ca0315eec83fc68e63b376b15aa136c10.png'))
if isinstance(results[0], AnimeSource):
    print(f"Title: {results[0].title}")
    print(f"Timestamp: {results[0].timestamp}")

Filtering

Index filtering

By default, SauceNao executes search queries on all indexes.

To limit your search to specific ones, build a list of indexes using the SauceNaoIndexes class and pass it to the SauceNao constructor.

For example, to only include search results from the social media indexes (such as Pixiv, Twitter, DeviantArt and so on), you can do the following,

from pysaucenao import SauceNao, SauceNaoIndexes
indexes = SauceNaoIndexes().add(SauceNaoIndexes.SOCIALS)
sauce = SauceNao(api_key='your_api_key', indexes=indexes)

To exclude specific indexes, make sure to call the add_all method first,

from pysaucenao import SauceNaoIndexes
indexes = SauceNaoIndexes().add_all().remove(SauceNaoIndexes.H_MISC)

For a full list of indexes, refer to the SauceNaoIndexes class.

Explicit content filtering

SauceNao's API provides an option to attempt to filter out explicit content from search results.

By default, pySauceNao does not apply any filtering.

If you wish to enable explicit content filtering, you can specify a filter level when constructing the SauceNao object,

from pysaucenao import SauceNao, SauceNaoFilter
sauce = SauceNao(api_key='your_api_key', filter_level=SauceNaoFilter.SAFE_ONLY)

SAFE_ONLY is the most aggressive filtering level, which attempts to only return results that SauceNao believes are "safe-for-work".

The other two options are EXPLICIT, which only filters results SauceNao has a high confidence are explicit, and POTENTIALLY_EXPLICIT which offers a middle ground in-between EXPLICIT and SAFE_ONLY.

Error handling

pySauceNao raises a SauceNaoError if an error occurs while executing an API query.

The following exceptions are subclasses of SauceNaoError and allow you to handle specific errors,

  • SauceNaoServerError: The SauceNao server is currently down.
  • InvalidApiKeyError: The API key you provided is invalid.
  • RateLimitedError: You have exceeded your search query limit. Provides a limit_type attribute that is either short, daily, or invalid_requests.
    • short: You have exceeded your 30-second search query limit.
    • daily: You have exceeded your 24-hour search query limit.
    • invalid_requests: You have made too many invalid requests in a short time period.
  • UploadError: The image provided was too large or not a valid image. You can also catch more specific UploadError exceptions,
    • FileSizeError: The image was too large.
    • InvalidImageError: The image was not a valid image.
  • BannedError: The API key you provided has been banned from use.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pysaucenao-2.0.1.tar.gz (62.3 kB view details)

Uploaded Source

Built Distribution

pysaucenao-2.0.1-py3-none-any.whl (14.2 kB view details)

Uploaded Python 3

File details

Details for the file pysaucenao-2.0.1.tar.gz.

File metadata

  • Download URL: pysaucenao-2.0.1.tar.gz
  • Upload date:
  • Size: 62.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.13.3

File hashes

Hashes for pysaucenao-2.0.1.tar.gz
Algorithm Hash digest
SHA256 f1fd90c3747788aa179544572031af767bde5ca118886f596c5240b351809479
MD5 feb6b0b97b4c17e4ea250fa80c7e590b
BLAKE2b-256 411e76a5c6467f55989ed119ef7ce476387741633180b77b626dfdb041c53cac

See more details on using hashes here.

File details

Details for the file pysaucenao-2.0.1-py3-none-any.whl.

File metadata

  • Download URL: pysaucenao-2.0.1-py3-none-any.whl
  • Upload date:
  • Size: 14.2 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.13.3

File hashes

Hashes for pysaucenao-2.0.1-py3-none-any.whl
Algorithm Hash digest
SHA256 4f3fa1e72c055a58defd739bcb2388ce64fc06093cc7c6ab89fa21b706c8dbda
MD5 2cf3634cf507e8f16364c33d14425022
BLAKE2b-256 5927070eaeea0e5a988ca98745e7efd02a0c436664d7185bcde864c83e1aaf0d

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page