{"id":15066768,"url":"https://github.com/largereptile/osutools","last_synced_at":"2025-04-10T13:53:29.063Z","repository":{"id":47647600,"uuid":"333994238","full_name":"largereptile/osutools","owner":"largereptile","description":"osu api wrapper + database reader in python","archived":false,"fork":false,"pushed_at":"2021-07-22T23:49:00.000Z","size":11264,"stargazers_count":10,"open_issues_count":2,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-03-21T14:55:10.590Z","etag":null,"topics":["api","databases","osu","python","python-3"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/largereptile.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-01-29T00:35:57.000Z","updated_at":"2024-09-09T14:30:11.000Z","dependencies_parsed_at":"2022-09-15T18:02:58.571Z","dependency_job_id":null,"html_url":"https://github.com/largereptile/osutools","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/largereptile%2Fosutools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/largereptile%2Fosutools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/largereptile%2Fosutools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/largereptile%2Fosutools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/largereptile","download_url":"https://codeload.github.com/largereptile/osutools/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248229087,"owners_count":21068821,"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":["api","databases","osu","python","python-3"],"created_at":"2024-09-25T01:11:54.283Z","updated_at":"2025-04-10T13:53:29.046Z","avatar_url":"https://github.com/largereptile.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# osu!-tools for python\n\n[![GitHub license](https://img.shields.io/github/license/largereptile/osutools)](https://github.com/largereptile/osutools/blob/main/LICENSE.md)\n[![GitHub stars](https://img.shields.io/github/stars/largereptile/osutools)](https://github.com/largereptile/osutools/stargazers)\n[![PyPI - Downloads](https://img.shields.io/pypi/dm/osu-tools)](https://pypi.org/project/osu-tools/)\n![Tests](https://github.com/largereptile/osutools/actions/workflows/python-package.yml/badge.svg)\n\n# Description\nosu!-tools is a Python framework for interacting with various osu! APIs and file-types.\n- Make requests to the osu! v1 API to view user, score, map or match information.\n- Uses oppai-ng to get pp information for any given score\n- Read osu!.db, scores.db and collection.db into a Python object, and export it to json\n\n\n# Installation\n```bash\npip install osu-tools\n```\n\n\n# Basic Examples\n## API v1\n```python console\n\u003e\u003e import osutools\n\n\n# Authenticate a client using an osu! API token\n\u003e\u003e osu = osutools.OsuClient(\"token\")\n```\n\n### Get User\n```python console\n\u003e\u003e me = osu.fetch_user(username=\"flubb 4\")\n\u003e\u003e print(f\"{me} | {me.pp}pp | #{me.rank} Global\")\n\nflubb 4 | 7507.3pp | #8765 Global\n```\n\n\n### Get best 5 scores + show information\n```python console\n\u003e\u003e best = me.fetch_best()[:5]\n\n\n\u003e\u003e for score in best:\n..  beatmap = score.fetch_map()\n..  print(f\"{score.pp}pp | {score.score} | {beatmap} | {score.mods}\")\n\n431.448pp | 1554216 | WONDERFUL WONDER (TV Size) [Simple Heart] mapped by Kuki1537 | DT\n399.029pp | 44559304 | Flames Within These Black Feathers [Kowari's Extreme] mapped by Seni | NM\n387.581pp | 2219153 | Angel With A Shotgun (Sped Up Ver.) [Sacred Bullet] mapped by Sotarks | HDDT\n379.095pp | 377539970 | Save Me [Tragedy] mapped by Drummer | NM\n371.206pp | 6547546 | One by One [Sotarks' Rampage] mapped by Elinor | HR\n```\n\n\n### Get information about a specific beatmap\n```python console\n\u003e\u003e beatmap = osu.fetch_map(map_id=2788620)\n\u003e\u003e print(f\"{beatmap.song_title} [{beatmap.difficulty_name}] | {beatmap.artist} | {beatmap.creator_name}\")\n\nSofia [Nyantiaz's Hard] | Clairo | Qiyana\n```\n\n\n### Get leaderboards and submitted scores for the beatmap\n```python console\n\u003e\u003e leaderboard = beatmap.fetch_scores()\n\u003e\u003e my_score = beatmap.fetch_scores(username=\"flubb 4\")[0]\n\u003e\u003e print(f\"Best Score: {leaderboard[0]}\\nMy Score: {my_score}\")\n\nBest Score: HDDTHR score on beatmap 2788620 by Mikayla\nMy Score: HDDT score on beatmap 2788620 by flubb 4\n```\n\n\n## Databases\n\n### Set osu directory, and automatically read the databases.\n```python console\n\u003e\u003e osu.set_osu_folder(\"path/to/folder\")\n\n# Load the pp values for all local plays (enables faster processing of functions that use the pp value like get_best_scores_before()\n\u003e\u003e osu.scores_db.load_pp()\n```\n\n\n### Get the average length of all of your maps\n```python console\n\u003e\u003e avg_map_length = sum([beatmap.length for beatmap in osu.osu_db.map_list()]) / float(len(osu.osu_db.map_list()))\n\u003e\u003e print(timedelta(milliseconds=avg_map_length))\n\n0:02:35.320889\n```\n\n\n### Get your top 10 ranked scores before 2020\n```python console\n\u003e\u003e names = [\"flubb 4\", \"ito\", \"biglizard\"] # I've changed my username a lot\n\u003e\u003e scores = osu.scores_db.get_best_scores_before(datetime.datetime(year=2020, month=1, day=1, tzinfo=timezone.utc), names=, ranked_only=True)\n\u003e\u003e for x, score in enumerate(scores[:5]):\n..    print(f\"{x+1}: {score.pp} play on {score.map.song_title} [{score.map.difficulty_name}] with {score.mods}\")\n\n1: 312.0760803222656 play on Snow Halation (feat. BeasttrollMC) [Reform's Extra] with DT\n2: 311.7738952636719 play on Harumachi Clover (Swing Arrangement) [Dictate Edit] [Expert] with DT\n3: 277.50250244140625 play on Yuki no Hana [Sharlo's Insane] with DT\n4: 272.4308776855469 play on Kira Kira Days [Shiawase!!] with NM\n5: 269.6291198730469 play on Natsukoi Hanabi [Insane] with DT\n```\n\n\n### Export your databases to JSON\n```python console\n\u003e\u003e osu.osu_db.export() # saves to osu_db.json by default\n\u003e\u003e osu.scores_db.export(\"~/osu/scores.json\") # can give custom path\n```\n\n\n## PP Calculation\n\n### Get pp for an SS on a given map with HDHR\n```python console\n\u003e\u003e from osutools.utils import Mods\n\u003e\u003e from osutools.oppai import Oppai\n\n\u003e\u003e beatmap_path = \"96neko - Uso no Hibana (Enjoy) [Hanabi].osu\"\n\u003e\u003e mod_combo = Mods.HR \u0026 Mods.HD\n\u003e\u003e pp = Oppai.calculate_pp(beatmap_path, mods=mod_combo.value)\n\u003e\u003e print(pp)\n\n219.83245849609375\n```\n\n\n### Get pp for an online map\n```python console\n\u003e\u003e beatmap = osu.fetch_map(1255495)\n\u003e\u003e pp = Oppai.calculate_pp_from_url(beatmap.download_url, mods=mod_combo.value, accuracy=99.5)\n\u003e\u003e print(pp)\n\n311.27484130859375\n```\n\n# Todo\n- api v2\n- better errors\n- probably some kind of internal ratelimit prevention?\n- tests 👀\n- discord integration utilities?\n- download beatmap\n\n\n# Acknowledgements\n- https://github.com/Francesco149/oppai-ng for the PP calculation, I just used ctypes to make it python\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flargereptile%2Fosutools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flargereptile%2Fosutools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flargereptile%2Fosutools/lists"}