{"id":13545450,"url":"https://github.com/nomnoms12/saucenao_api","last_synced_at":"2025-04-02T15:31:09.225Z","repository":{"id":41882072,"uuid":"265331176","full_name":"nomnoms12/saucenao_api","owner":"nomnoms12","description":"Wrapper for SauceNAO JSON API","archived":false,"fork":false,"pushed_at":"2023-06-29T15:29:04.000Z","size":116,"stargazers_count":64,"open_issues_count":4,"forks_count":13,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-03-15T02:46:55.226Z","etag":null,"topics":["python","python-api-wrapper","saucenao","saucenao-api"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/saucenao-api","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nomnoms12.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2020-05-19T18:32:35.000Z","updated_at":"2024-02-03T10:09:29.000Z","dependencies_parsed_at":"2024-01-14T19:14:26.611Z","dependency_job_id":"d6517a83-3807-4513-9fac-fcd7ccd56f25","html_url":"https://github.com/nomnoms12/saucenao_api","commit_stats":{"total_commits":60,"total_committers":4,"mean_commits":15.0,"dds":"0.050000000000000044","last_synced_commit":"c4121644222079ce62733566f4dcb6d31122d432"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nomnoms12%2Fsaucenao_api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nomnoms12%2Fsaucenao_api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nomnoms12%2Fsaucenao_api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nomnoms12%2Fsaucenao_api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nomnoms12","download_url":"https://codeload.github.com/nomnoms12/saucenao_api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246841653,"owners_count":20842626,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["python","python-api-wrapper","saucenao","saucenao-api"],"created_at":"2024-08-01T11:01:02.981Z","updated_at":"2025-04-02T15:31:07.899Z","avatar_url":"https://github.com/nomnoms12.png","language":"Python","readme":"![SauceNAO Logo](https://user-images.githubusercontent.com/44947427/89287471-b9289000-d65c-11ea-905d-aa72f908a9b3.png)\n\n# saucenao_api\n[![Tests](https://github.com/nomnoms12/saucenao_api/workflows/Tests/badge.svg?branch=master)](https://github.com/nomnoms12/saucenao_api/actions?query=workflow%3ATests)\n[![codecov](https://codecov.io/gh/nomnoms12/saucenao_api/branch/master/graph/badge.svg)](https://codecov.io/gh/nomnoms12/saucenao_api)\n[![License](https://img.shields.io/github/license/nomnoms12/saucenao_api)](https://github.com/nomnoms12/saucenao_api/blob/master/LICENSE)\n[![SauceNao Status](https://img.shields.io/website?url=https%3A%2F%2Fsaucenao.com)](https://saucenao.com)\n[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/saucenao_api)](https://pypi.org/project/saucenao-api)\n\n\u003e “The rough edges are a part of its charm”\n\nUnofficial wrapper for the [SauceNAO](https://saucenao.com) JSON API\n\n# Installation\nThis package requires Python 3.6 or later.\n```\npip install -U saucenao_api\n```\n\n# Usage\n```python\nfrom saucenao_api import SauceNao\n\n# Replace the key with your own\nsauce = SauceNao('077f16b38a2452401790540f41246c7d951330c0')\nresults = sauce.from_url('https://i.imgur.com/oZjCxGo.jpg')  # or from_file()\n\nbest = results[0]  # results sorted by similarity\n```\n\nThe 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:\n```python\nfrom saucenao_api import SauceNao\nresults = SauceNao('077f16b38a2452401790540f41246c7d951330c0').from_url('https://i.imgur.com/oZjCxGo.jpg')\n\nlen(results)   # 6\nbool(results)  # True\n\n# Request limits\nresults.short_remaining  # 4  (per 30 seconds limit)\nresults.long_remaining   # 99 (per day limit)\n\nresults[0].thumbnail     # temporary URL for picture preview\nresults[0].similarity    # 93.3\nresults[0].title         # めぐみん\nresults[0].urls          # ['https://www.pixiv.net/member_illust.php?mode=medium\u0026illust_id=77630170']\nresults[0].author        # frgs\nresults[0].raw           # raw result\n```\n\nVideo search results and book search results provide additional attributes:\n```python\nfrom saucenao_api import SauceNao, VideoSauce, BookSauce\nresult = SauceNao('077f16b38a2452401790540f41246c7d951330c0').from_url('https://i.imgur.com/k9xlw6f.jpg')[0]\n\nif isinstance(result, VideoSauce):\n    result.part      # 02\n    result.year      # 2009-2009\n    result.est_time  # 00:05:32 / 00:21:10\n\nelif isinstance(result, BookSauce):\n    result.part\n```\n*You can use the `dir` function to see all the attributes.*\n\n## Asyncio\n```python\nimport asyncio\nfrom saucenao_api import AIOSauceNao\n\nasync def main():\n    # async requesting is also supported via the AIOSauceNao class\n    async with AIOSauceNao('077f16b38a2452401790540f41246c7d951330c0') as aio:\n        results = await aio.from_url('https://i.imgur.com/k9xlw6f.jpg')\n    \nasyncio.run(main())\n```\nThe async with functionality is pretty useful if you want to make multiple requests.\nNote that you can still search without the `async with` syntax by simply calling `await AIOSauceNao(...).from_url(...)`.\n\n## Advanced usage\n```python\nfrom saucenao_api import SauceNao\nfrom saucenao_api.params import DB, Hide, BgColor\n\nsauce = SauceNao(api_key=None,          # Optional[str] \n                 testmode=0,            # int\n                 dbmask=None,           # Optional[int]\n                 dbmaski=None,          # Optional[int]\n                 db=DB.ALL,             # int\n                 numres=6,              # int\n                 frame=1,               # int\n                 hide=Hide.NONE,        # int\n                 bgcolor=BgColor.NONE,  # int\n)\n```\nThe parameters `frame`, `hide` and `bgcolor` are taken from the main page and from the [testing page](https://saucenao.com/testing), so their performance is not guaranteed. For the rest see [SauceNAO User Config](https://saucenao.com/user.php?page=search-api) page (registration required).\n\n### Exceptions\nAll exceptions inherit from `SauceNaoApiError` for easy catching and handling. See [`errors.py`](saucenao_api/errors.py) file for details.\n\n*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.*\n\n# License\nThis package is based on [`pysaucenao`](https://github.com/FujiMakoto/pysaucenao).\n","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnomnoms12%2Fsaucenao_api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnomnoms12%2Fsaucenao_api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnomnoms12%2Fsaucenao_api/lists"}