{"id":15896216,"url":"https://github.com/numberoverzero/oga","last_synced_at":"2025-03-20T15:32:37.103Z","repository":{"id":48335941,"uuid":"118501888","full_name":"numberoverzero/oga","owner":"numberoverzero","description":"A simple tool to search and download assets from OpenGameArt.org","archived":false,"fork":false,"pushed_at":"2021-07-31T18:30:05.000Z","size":49,"stargazers_count":3,"open_issues_count":1,"forks_count":3,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-10-07T09:06:41.160Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/numberoverzero.png","metadata":{"files":{"readme":"README.rst","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}},"created_at":"2018-01-22T19:06:39.000Z","updated_at":"2024-06-03T20:23:31.000Z","dependencies_parsed_at":"2022-09-15T16:40:41.149Z","dependency_job_id":null,"html_url":"https://github.com/numberoverzero/oga","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/numberoverzero%2Foga","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/numberoverzero%2Foga/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/numberoverzero%2Foga/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/numberoverzero%2Foga/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/numberoverzero","download_url":"https://codeload.github.com/numberoverzero/oga/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221776117,"owners_count":16878490,"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":[],"created_at":"2024-10-06T09:06:56.525Z","updated_at":"2024-10-28T04:02:39.465Z","avatar_url":"https://github.com/numberoverzero.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"OpenGameArt Asset Management\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nPrimarily exists to query and download assets from OpenGameArt.  This library does not manage collections, post or edit\ncomments.  In the future, it may be used to upload or modify your assets.\n\nInstallation\n============\n\n::\n\n    pip install oga\n\nUsing the CLI\n=============\n\nThe cli can be used for searching, downloading, and describing assets.\n\n::\n\n    $ oga --help\n    Usage: oga [OPTIONS] COMMAND [ARGS]...\n\n      Search and download assets from OpenGameArt.org\n\n    Options:\n      --config-path PATH\n      --root-dir DIRECTORY\n      --url TEXT\n      --max-conns INTEGER\n      --help                Show this message and exit.\n\n    Commands:\n      describe  Look up a single ASSET.\n      download  Download files for a single ASSET.\n      search    Search for an asset.\n\nSample Commands\n---------------\n\nDescribe a single asset.  The asset id is everything after ``/content/`` in the OpenGameArt url::\n\n    $ oga describe imminent-threat\n    imminent-threat music (37 favorites, 22 tags)\n\nDownload a single asset::\n\n    $ oga download imminent-threat\n\nA simple per-file etag-based cache is used to avoid re-downloading the same blobs::\n\n    $ time oga download imminent-threat\n\n    real    0m8.443s\n    user    0m1.944s\n    sys\t0m0.592s\n    $ time oga download imminent-threat\n\n    real    0m0.780s\n    user    0m0.444s\n    sys\t0m0.080s\n\nIn the future, describe and download operations should be much faster for recently-queried packages since today,\nthe asset etag is not checked and the asset description is not cached (only the file etags are).\n\nSearch for assets::\n\n    $ oga search --type music --tag epic --tag viking\n    heroic-demise-updated-version music (86 favorites, 12 tags)\n    battle-theme-a music (76 favorites, 6 tags)\n    rise-of-spirit music (71 favorites, 4 tags)\n    space-boss-battle-theme music (57 favorites, 31 tags)\n    rpg-battle-theme-the-last-encounter-0 music (53 favorites, 26 tags)\n    dark-descent music (44 favorites, 8 tags)\n    dream-raid-cinematic-action-soundtrack music (44 favorites, 17 tags)\n    space-orchestral music (41 favorites, 3 tags)\n    # ...\n\n    $ oga search --type music --tag epic --tag viking --tag-op and\n    # no results with both tags!\n\n    $ oga search --type music --license cc0 --tag epic\n    battle-theme-a music (76 favorites, 6 tags)\n    boss-battle-music music (19 favorites, 3 tags)\n    new-sunrise music (9 favorites, 15 tags)\n    the-rush music (8 favorites, 13 tags)\n    # ...\n\nOutput Format\n-------------\n\nThe default output for an asset is a short summary, which can be cut and piped to other commands.  Its format is::\n\n    \u003casset_id\u003e \u003ctype\u003e (\u003c\\d+\u003e favorites, \u003c\\d+\u003e tags)\n\n    # oga search --submitter xmo --type 3d --type texture\n    graveyard-and-crypt 3d (10 favorites, 11 tags)\n    my-blender-skins texture (7 favorites, 9 tags)\n    posable-poultry 3d (6 favorites, 9 tags)\n\nUsing the usual tools, you can pipe this to other commands eg. download::\n\n    oga search --submitter xmo --type 3d --type texture \\\n      | cut -d\" \" -f1 \\\n      | xargs -n1 oga download\n\nMore asset details are available using ``--verbose``::\n\n    $ oga describe imminent-threat --verbose\n    {\n        \"attribution\": null,\n        \"author\": \"matthew-pablo\",\n        \"favorites\": 37,\n        \"files\": [\n            {\n                \"etag\": \"2e9386d-4f63b81cc5d00\",\n                \"id\": \"Imminent Threat Collection.zip\",\n                \"size\": 48838765\n            }\n        ],\n        \"id\": \"imminent-threat\",\n        \"licenses\": [\n            \"CC-BY-SA 3.0\"\n        ],\n        \"tags\": [\n            \"Action\",\n            \"stealth\",\n            \"Battle\",\n            \"combat\",\n            \"covert\",\n            \"Rock\",\n            \"hard\",\n            \"metal\",\n            \"hardcore\",\n            \"piano\",\n            \"soft\",\n            \"scary\",\n            \"horror\",\n            \"suspense\",\n            \"epic\",\n            \"drumset\",\n            \"title\",\n            \"violent\",\n            \"dark\",\n            \"serious\",\n            \"metal gear\",\n            \"call of duty\"\n        ],\n        \"type\": \"Music\"\n    }\n\nUsing the Library\n=================\n\nDownloading Assets\n------------------\n\nOne Asset\n^^^^^^^^^\n\nDownload an asset in 5 lines:\n\n.. code-block:: python\n\n    \u003e\u003e\u003e from oga import Session\n    \u003e\u003e\u003e session = Session()\n    \u003e\u003e\u003e asset_id = \"imminent-threat\"\n    \u003e\u003e\u003e asset = session.loop.run_until_complete(session.describe_asset(asset_id))\n    \u003e\u003e\u003e session.loop.run_until_complete(session.download_asset(asset))\n\nMultiple Assets\n^^^^^^^^^^^^^^^\n\nLet's take advantage of the async client and download a few assets at once:\n\n.. code-block:: python\n\n    \u003e\u003e\u003e import asyncio\n    \u003e\u003e\u003e from oga import Config, Session\n    \u003e\u003e\u003e config = Config.default()\n    \u003e\u003e\u003e config.max_conns = 200  # please be nice\n    \u003e\u003e\u003e session = Session(config)\n\n    \u003e\u003e\u003e async def download(asset_id):\n    ...     asset = await session.describe_asset(asset_id)\n    ...     await session.download_asset(asset)\n    ...\n\n    \u003e\u003e\u003e asset_ids = [\n    ...     \"free-music-pack\",\n    ...     \"battle-theme-a\",\n    ...     \"rise-of-spirit\",\n    ...     \"town-theme-rpg\",\n    ...     \"soliloquy\"]\n\n    \u003e\u003e\u003e task = asyncio.wait(\n    ...     [download(id) for id in asset_ids],\n    ...     loop=session.loop,\n    ...     return_when=asyncio.ALL_COMPLETED)\n\n    \u003e\u003e\u003e session.loop.run_until_complete(task)\n\nCaching\n^^^^^^^\n\nThis library uses a very simple (dumb) tracker to avoid re-downloading asset files based on the ``ETag`` of each\nfile.  Because OGA doesn't publish a content hash it's possible to modify the downloaded file and you'll break the\ntracking.\n\nSearching For Assets\n--------------------\n\nSearches use asynchronous generators so that you don't need to fetch every result to begin processing them.\n\n.. code-block:: python\n\n    from oga import Session\n    session = Session()\n\n    # submitter name begins with or contains 'xmo'\n    search = session.search(submitter=\"xmo\")\n\n    async def collect(async_generator):\n        \"\"\"Helper to block and collapse an async generator into a single list\"\"\"\n        results = []\n        async for result in async_generator:\n            results.append(result)\n        return results\n\n    results = session.loop.run_until_complete(collect(search))\n    print(results)\n    # ['graveyard-and-crypt', 'my-blender-skins', 'posable-poultry']\n\nSynchronous Client\n------------------\n\nThe synchronous client exposes batched operations of ``Session.download_asset`` and ``Session.describe_asset``.\n\n\n.. code-block:: python\n\n    \u003e\u003e\u003e from oga import SynchronizedSession\n    \u003e\u003e\u003e session = SynchronizedSession()\n    \u003e\u003e\u003e assets = session.batch_describe_assets([\n    ...     \"free-music-pack\",\n    ...     \"battle-theme-a\",\n    ...     \"rise-of-spirit\",\n    ...     \"town-theme-rpg\",\n    ...     \"soliloquy\"\n    ... ])\n    \u003e\u003e\u003e session.batch_download_assets(assets.values())\n\nTODO\n====\n\nRoughly ordered by priority.\n\n* docstrings\n* community feature requests?\n* unit tests\n* rtd\n* hook points for status updates (eg. progress bars for long downloads)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnumberoverzero%2Foga","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnumberoverzero%2Foga","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnumberoverzero%2Foga/lists"}