Skip to main content

Wrapper for SauceNAO JSON API

Project description

SauceNAO Logo

saucenao_api

Tests codecov License SauceNao Status PyPI - Python Version

“The rough edges are a part of its charm”

Unofficial wrapper for the SauceNAO JSON API

Installation

This package requires Python 3.6 or later.

pip install -U saucenao_api

Usage

from saucenao_api import SauceNao

# Replace the key with your own
sauce = SauceNao('077f16b38a2452401790540f41246c7d951330c0')
results = sauce.from_url('https://i.imgur.com/oZjCxGo.jpg')  # or from_file()

best = results[0]  # results sorted by similarity

The library attempts to provide a developer friendly container format for all results. Meaning, no matter if SauceNao returns a Pixiv source result or a more obscure source, you'll be able to easily pull the title, urls, author and other useful information:

from saucenao_api import SauceNao
results = SauceNao('077f16b38a2452401790540f41246c7d951330c0').from_url('https://i.imgur.com/oZjCxGo.jpg')

len(results)   # 6
bool(results)  # True

# Request limits
results.short_remaining  # 4  (per 30 seconds limit)
results.long_remaining   # 99 (per day limit)

results[0].thumbnail     # temporary URL for picture preview
results[0].similarity    # 93.3
results[0].title         # めぐみん
results[0].urls          # ['https://www.pixiv.net/member_illust.php?mode=medium&illust_id=77630170']
results[0].author        # frgs
results[0].raw           # raw result

Video search results and book search results provide additional attributes:

from saucenao_api import SauceNao, VideoSauce, BookSauce
result = SauceNao('077f16b38a2452401790540f41246c7d951330c0').from_url('https://i.imgur.com/k9xlw6f.jpg')[0]

if isinstance(result, VideoSauce):
    result.part      # 02
    result.year      # 2009-2009
    result.est_time  # 00:05:32 / 00:21:10

elif isinstance(result, BookSauce):
    result.part

You can use the dir function to see all the attributes.

Asyncio

import asyncio
from saucenao_api import AIOSauceNao

async def main():
    # async requesting is also supported via the AIOSauceNao class
    async with AIOSauceNao('077f16b38a2452401790540f41246c7d951330c0') as aio:
        results = await aio.from_url('https://i.imgur.com/k9xlw6f.jpg')

asyncio.run(main())

The async with functionality is pretty useful if you want to make multiple requests. Note that you can still search without the async with syntax by simply calling await AIOSauceNao(...).from_url(...).

Advanced usage

from saucenao_api import SauceNao
from saucenao_api.params import DB, Hide, BgColor

sauce = SauceNao(api_key=None,          # Optional[str] 
                 testmode=0,            # int
                 dbmask=None,           # Optional[int]
                 dbmaski=None,          # Optional[int]
                 db=DB.ALL,             # int
                 numres=6,              # int
                 frame=1,               # int
                 hide=Hide.NONE,        # int
                 bgcolor=BgColor.NONE,  # int
)

The parameters frame, hide and bgcolor are taken from the main page and from the testing page, so their performance is not guaranteed. For the rest see SauceNAO User Config page (registration required).

Exceptions

All exceptions inherit from SauceNaoApiError for easy catching and handling. See errors.py file for details.

Note: SauceNao doesn't have good documentation. Exceptions are created only based on observations of changes in the returned status codes. If you find a specific error that is not being processed, please report it.

License

This package is based on pysaucenao.

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

saucenao_api-2.4.0.tar.gz (20.4 kB view details)

Uploaded Source

Built Distribution

saucenao_api-2.4.0-py3-none-any.whl (20.0 kB view details)

Uploaded Python 3

File details

Details for the file saucenao_api-2.4.0.tar.gz.

File metadata

  • Download URL: saucenao_api-2.4.0.tar.gz
  • Upload date:
  • Size: 20.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.4.2 importlib_metadata/4.8.1 pkginfo/1.7.1 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.62.2 CPython/3.8.11

File hashes

Hashes for saucenao_api-2.4.0.tar.gz
Algorithm Hash digest
SHA256 387603a95166e88121e2e293ddb1c7c9f9c9757ead6731b5e077197841bf8985
MD5 89f13c572edf5ffe1711cfcc3e07e14b
BLAKE2b-256 cf4c3967f981ea2595734e03ca29f4beb3beaf155d53cffd4799cc053dd8e3dd

See more details on using hashes here.

File details

Details for the file saucenao_api-2.4.0-py3-none-any.whl.

File metadata

  • Download URL: saucenao_api-2.4.0-py3-none-any.whl
  • Upload date:
  • Size: 20.0 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.4.2 importlib_metadata/4.8.1 pkginfo/1.7.1 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.62.2 CPython/3.8.11

File hashes

Hashes for saucenao_api-2.4.0-py3-none-any.whl
Algorithm Hash digest
SHA256 dd684e34a4746a04dd499cab323df21fd0aa93d8092aaaf8f249df79e4d5a731
MD5 b78909ad29695d43081cc2a95bed69b7
BLAKE2b-256 96eeb5ff3586d2d8787b491b930e378986262caaa5be2ac00491f6a4a36fee1c

See more details on using hashes here.

Supported by

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