{"id":25077396,"url":"https://github.com/reluce/szurubooru-toolkit","last_synced_at":"2025-04-05T22:04:57.394Z","repository":{"id":45424757,"uuid":"353998600","full_name":"reluce/szurubooru-toolkit","owner":"reluce","description":"Python package and script collection to manage your szurubooru image board.","archived":false,"fork":false,"pushed_at":"2025-03-13T22:58:31.000Z","size":826,"stargazers_count":47,"open_issues_count":7,"forks_count":13,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-01T12:09:18.423Z","etag":null,"topics":["auto-tagger","auto-tagging","automation","bash","image-board","python","saucenao","scripts","szuru","szurubooru","tagging","uploader"],"latest_commit_sha":null,"homepage":"","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/reluce.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,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-04-02T11:27:20.000Z","updated_at":"2025-03-13T22:58:35.000Z","dependencies_parsed_at":"2023-10-16T12:56:54.098Z","dependency_job_id":"3c3b0946-f0d8-4c25-b39f-11d50240ee7a","html_url":"https://github.com/reluce/szurubooru-toolkit","commit_stats":{"total_commits":293,"total_committers":4,"mean_commits":73.25,"dds":0.07508532423208192,"last_synced_commit":"a756809efa3001c0f492b58dd39aa5a419ac37bb"},"previous_names":[],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reluce%2Fszurubooru-toolkit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reluce%2Fszurubooru-toolkit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reluce%2Fszurubooru-toolkit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reluce%2Fszurubooru-toolkit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/reluce","download_url":"https://codeload.github.com/reluce/szurubooru-toolkit/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247406085,"owners_count":20933803,"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":["auto-tagger","auto-tagging","automation","bash","image-board","python","saucenao","scripts","szuru","szurubooru","tagging","uploader"],"created_at":"2025-02-07T02:24:58.642Z","updated_at":"2025-04-05T22:04:57.343Z","avatar_url":"https://github.com/reluce.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://cdn-icons-png.flaticon.com/512/2581/2581053.png\"\n  alt=\"szurubooru-toolkit icon\"\n  width=\"128\" height=\"128\"\u003e\n\u003c/p\u003e\n\n# szurubooru-toolkit\nPython package and script collection to manage your [szurubooru](https://github.com/rr-/szurubooru) image board.\n```\nUsage: szuru-toolkit [OPTIONS] COMMAND [ARGS]...\n\n  Toolkit to manage your szurubooru image board.\n\n  Defaults can also be set in a config file.\n\n  Visit https://github.com/reluce/szurubooru-toolkit for more information.\n\nOptions:\n  --url TEXT                      Base URL to your szurubooru instance.\n  --username TEXT                 Username which will be used to authenticate with the szurubooru API.\n  --api-token TEXT                API token for the user which will be used to authenticate with the szurubooru API.\n  --public                        If your szurubooru instance is reachable from the internet (default: False).\n  --log-enabled                   Create a log file (default: False).\n  --log-colorized                 Colorize the log output (default: True).\n  --log-file TEXT                 Output file for the log (default: szurubooru_toolkit.log)\n  --log-level [DEBUG|INFO|WARNING|ERROR|CRITICAL]\n                                  Set the log level (default: INFO).\n  --hide-progress                 Hides the progress bar (default: False).\n  -h, --help                      Show this message and exit.\n\nCommands:\n  auto-tagger        Tag posts automatically\n  create-relations   Create relations between character and parody tag categories\n  create-tags        Create tags based on a tag file or query\n  delete-posts       Delete posts\n  import-from-booru  Download and tag posts from various Boorus\n  import-from-url    Download images from URLS or file containing URLs\n  reset-posts        Remove tags and sources\n  tag-posts          Tag posts manually\n  upload-media       Upload media files\n```\n## :ballot_box_with_check: Requirements\nIn order to run `szuru-toolkit`, Python `3.11` is required.\n\n## :hammer_and_wrench: Installation\nThis package is available on [PyPI](https://pypi.org/project/szurubooru-toolkit/) and can be installed with pip:\n`pip install szurubooru-toolkit`\n\nAlternatively, you can clone the package from GitHub and set everything up with [Poetry](https://python-poetry.org/docs/). In the root directory of this repository, execute `poetry install`.\n\n### Docker Instructions\nIf you would like to run the toolkit in a Docker container instead, follow the\ninstructions below.\n\u003cdetails\u003e\n1. Copy `docker-compose.yml` to the location where you want to run the toolkit.\n\n1. Copy `config_sample.toml` to the same location, renaming to `config.toml` and\nreplacing with your configuration.\n\n1. Copy `crontab_sample` to the same location, renaming to `crontab` and adding\n   the commands you would like to run regularly. An example command is provided\n   in `crontab_sample`.\n\n1. Make sure to set the `src_path` option in `config.toml` to use\n   `/szurubooru-toolkit/upload_src`. If you're using a different directory than\n   `upload_src`, you may need to update the `docker-compose.yml` binding to be\n   something like `./uploads:/szurubooru-toolkit/uploads`, and set\n   `/szurubooru-toolkit/uploads` as the `src_path` option instead.\n\n1. Create the folder `tmp` in the same location.\n\n1. If you would like to use deepbooru or tag files, create `misc/deepbooru`\n   and/or `misc/tags` in the same location and follow the instructions linked\n   below\n\n1. Run `touch szurubooru_toolkit.log` in the same location to create a file for\n   the log. You may need to set the log location to\n   `/szurubooru-toolkit/szurubooru_toolkit.log` in `config.toml`\n\n1. Use `docker-compose up` or `docker-compose up -d` to start the container, or\n   start the container in the background, respectively. You can use\n   `docker-compose logs` or `docker-compose logs -f` to inspect the container\n   output, which will include szuru toolkit's output if you append your cron\n   jobs with `\u003e/proc/1/fd/1 2\u003e\u00261` like in the example job.\n\n1. If you just want to run a one-time command, leave the `crontab` file blank\n   and start the container with `docker-compose up -d`, taking note of the\n   `container_name` option in `docker-compose.yml`. Then, you can run commands\n   inside of the running container like this: `docker exec -it container_name\n   auto-tagger`, replacing `container_name` with the container name.\n\n1. If you would like the container to run a one-time command and then quit with\n   `docker-compose.yml`, add a `command` configuration [like\n   this](https://docs.docker.com/compose/compose-file/compose-file-v3/#command).\n\u003c/details\u003e\n\n## :memo: User configuration\nWhile the script `szuru-toolkit` can run with just command line options, you can also set your options in a config file.\n\nThe script looks for a `config.toml` file in following locations:\n\n### Linux\n* Your current working directory from which `szuru-toolkit` is executed\n* `~/.config/szurubooru-toolkit/config.toml`\n* `/etc/szurubooru-toolkit/config.toml`\n\n### Windows\n* Your current working directory from which `szuru-toolkit` is executed\n* `$USERPROFILE/szurubooru-toolkit/config.toml`\n* `$APPDATA/szurubooru-toolkit/config.toml`\n\nOptions passed to the `szuru-toolkit` script take priority over the config file.\n\nYou can find a sample config file in the [GitHub repository](https://github.com/reluce/szurubooru-toolkit) of this package.\n\nNote that path names have to be specified with forward slashes (/) if you're using Windows.\n\nCreating a SauceNAO account and an API key is recommended.\nPlease consider supporting the SauceNAO team as well by upgrading your plan.\nWith a free plan, you can request up to 200 posts in 24h.\n\nFor Deepbooru support, download the current release [here](https://github.com/KichangKim/DeepDanbooru/releases/tag/v3-20211112-sgd-e28) (v3-20211112-sgd-e28) and extract the contents of the zip file. Specify the path of the folder with the extracted files in `deepbooru_model`.\nPlease note that you have to set `deepbooru_enabled` if you want to use it.\n\n## :page_with_curl: Commands\nFollowing commands are currently available:\n\n* `auto-tagger`: Tag posts automatically\n* `create-relations`: Create relations between character and parody tag categories\n* `create-tags`: Create tags based on a tag file or query\n* `delete-posts`: Delete posts\n* `import-from-booru`: Download and tag posts from various Boorus\n* `import-from-url`: Batch importing of URLs based on [gallery-dl](https://github.com/mikf/gallery-dl)\n* `reset-posts`: Remove tags and sources\n* `tag-posts`: Tag posts manually\n* `upload-media`: Upload media files\n\nCheck `szuru-toolkit -h` or `szuru-toolkit COMMAND -h` for a detailed description of supported options.\n\nIf you cloned the repo from GitHub, prefix the above scripts with `poetry run`, e.g. `poetry run szuru-toolkit auto-tagger \"date:today\"`. Note that your current working directory has to be the the root of the GitHub project.\n\nIf your query starts with a dash (`-`), for example to negate a tag, you have to separate the query from the command with two dashes (This doesn't work with poetry run):\n\n`szuru-toolkit auto-tagger --no-deepbooru -- \"-foo bar\"`\n\nWhile most commands are self explanatory, the following require a bit of extra attention:\n\n### :label: create-relations\n__Examples__\n* `szuru-toolkit create-relations hitori_bocchi`\n  * Will create the implication _bocchi_the_rock_ for tag _hitori_bocchi_ if other posts are found with query _hitori_bocchi_ containing _bocchi_the_rock_ as the parody (tag has to be of category _series_ or _parody_)\n  * Will also add _hitori_bocchi_ as a suggestion to the parody tag _bocchi_the_rock_\n  * These relations will only get generated if at least X posts are found containing the tags _bocchi_the_rock_ and _hitori_bocchi_. Control X with `threshold` under `[create-relations]` in `config.toml`.\n\n### :label: create-tags\nIf no `tag_file` is specified, the script will download the most recent 100 tags from Danbooru which have been used at least ten times.\n\nYou can use tools like [Grabber](https://github.com/Bionus/imgbrd-grabber) to download a tag list from common boorus.\n\nThe `tag_file` has to be in following format:\n\n```\n\u003ctag_a\u003e,\u003ccategory_name\u003e\n\u003ctag_b\u003e,\u003ccategory_name\u003e\n\u003ctag_..n\u003e,\u003ccategory_name\u003e\n```\n\nThe category has to be created beforehand manually (e.g. default, artist, parody/series, character and meta).\n\n__Examples__\n* `szuru-toolkit create-tags`\n* `szuru-toolkit create-tags --query genshin* --overwrite`\n* `szuru-toolkit create-tags --tag-file tags.txt`\n\n### :link:\timport-from-url\nThis scripts imports posts with their tags from the URL passed to this script.\nIn the background, it simply calls the [gallery-dl](https://github.com/mikf/gallery-dl) script and parses its output.\nAlternatively, an input file with multiple URLs can be specified.\n\nIt's recommended to use the `--cookie` flag for authentication, check https://github.com/mikf/gallery-dl#cookies for details.\n\n__Usage__\n__Examples__\n* `szuru-toolkit import-from-url \"https://danbooru.donmai.us/posts?tags=foo\"`\n* `szuru-toolkit import-from-url \"https://chan.sankakucomplex.com/?tags=foo\"`\n* `szuru-toolkit import-from-url \"https://beta.sankakucomplex.com/post/show/\u003cid\u003e\"`\n* `szuru-toolkit import-from-url --cookies \"~/cookies.txt\" --range \":100\" \"\"https://twitter.com/\u003cUSERNAME\u003e/likes\"`\n* `szuru-toolkit import-from-url --input-file urls.txt \"https://danbooru.donmai.us/posts?tags=foo\" \"https://beta.sankakucomplex.com/post/show/\u003cid\u003e\"`\n\n## :information_source:\tImage credit\nGitHub repo icon: \u003ca href=\"https://www.flaticon.com/free-icons/code\" title=\"code icons\"\u003eCode icons created by Smashicons - Flaticon\u003c/a\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freluce%2Fszurubooru-toolkit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Freluce%2Fszurubooru-toolkit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freluce%2Fszurubooru-toolkit/lists"}