{"id":43107160,"url":"https://github.com/hltcoe/turkle-client","last_synced_at":"2026-01-31T18:11:03.092Z","repository":{"id":152338517,"uuid":"573185227","full_name":"hltcoe/turkle-client","owner":"hltcoe","description":"client for the Turkle annotation platform ","archived":false,"fork":false,"pushed_at":"2025-10-08T14:50:45.000Z","size":93,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-10-10T10:28:15.366Z","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":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hltcoe.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,"zenodo":null}},"created_at":"2022-12-01T22:08:08.000Z","updated_at":"2025-10-08T14:50:49.000Z","dependencies_parsed_at":null,"dependency_job_id":"fe62b133-eb21-4f16-b105-be2a2a01bddd","html_url":"https://github.com/hltcoe/turkle-client","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/hltcoe/turkle-client","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hltcoe%2Fturkle-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hltcoe%2Fturkle-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hltcoe%2Fturkle-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hltcoe%2Fturkle-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hltcoe","download_url":"https://codeload.github.com/hltcoe/turkle-client/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hltcoe%2Fturkle-client/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28949274,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-31T14:26:55.697Z","status":"ssl_error","status_checked_at":"2026-01-31T14:26:52.545Z","response_time":128,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":"2026-01-31T18:11:01.403Z","updated_at":"2026-01-31T18:11:03.073Z","avatar_url":"https://github.com/hltcoe.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Turkle Client\nThis is a client for the [Turkle](https://github.com/hltcoe/turkle) annotation platform.\nIt provides a commandline interface to create and work with users, groups, projects and batches.\nThere is also a client library for building utilities to interact with Turkle.\n\n## Install\nInstall from pip:\n```\npip install turkle-client\n```\n\n## CLI Usage\nThe commandline client works similar to tools like git where there is a hierarchy\nof commands. The top level commands are config, users, groups, projects, and batches.\nEach has sub-commands like retrieve, create, or update.\n\nTo get the top level documentation, pass the -h flag:\n```\nturkle-client -h\n```\nTo get documentation on an individual command:\n```\nturkle-client batches -h\n```\n\n### Configuration\nSet the url of the Turkle site and your token:\n```\nturkle-client config url https://example.org/\nturkle-client config token 41dcbb22264dd60c5232383fc844dbbab4839146\n```\nTo view your configuration:\n```\nturkle-client config print\n```\n\nThe token and url can also be specified on the command line:\n```\nturkle-client -u https://example.org -t abcdef users list\n```\n\n### Users\nTo list current users:\n```\nturkle-client users list\n```\n\nTo create users, create a CSV file like this:\n```\nusername,password,first_name,last_name,email\nsmithgc1,p@ssw0rd,george,smith,gcs@mail.com\njonesrt1,12345678,roger,jones,jones@mail.com\n```\nand then pass it to the client::\n```\nturkle-client users create --file new_users.csv\n```\nThe create command also accepts jsonl files.\n\nUpdating a user requires a json object with the id of the user and then\nany fields that you want to change:\n```\n{\"id\": 5, \"email\": \"my_new_addr@example.org\"}\n```\nand is passed to the command using the file argument:\n```\nturkle-client users update --file user_update.json\n```\n\n### Groups\nList groups with:\n```\nturkle-client groups list\n```\n\nCreating a group requires a jsonl or json file with the name and a \nlist of user IDs:\n```\n{\"name\":\"Spanish annotators\",\"users\":[3,7,54]}\n```\nand then passed to the command:\n```\nturkle-client groups create --file spanish.json\n```\n\nAdding users to a group requires a json file with the list of user IDs:\n```\n[2,4,17,34]\n```\nwhich is passed to the command with the group id:\n```\nturkle-client groups addusers --id 5 --file june_users.json\n```\n\n### Projects\nA project needs a template html file:\n```\n{\n  \"name\": \"Image Contains\",\n  \"filename\": \"~/templates/image_contains.html\"\n}\n```\nand the json object can have additional optional fields such as\nallotted_assignment_time and assignments_per_task.\n```\nturkle-client projects create --file myproject.json\n```\n\nTo get information about the batches that have been published for the project:\n```\nturkle-client projects batches --id 8\n```\n\n### Batches\nTo create a batch, you will need the name, project id, and csv file:\n```\n{\n  \"name\": \"Bird Photos\",\n  \"project\": 20,\n  \"filename\": \"image_contains.csv\",\n}\n```\nThe json object can have additional fields just like creating projects.\n```\nturkle-client batches create --file mybatch.json\n```\n\nGetting the progress, the input csv or the results csv all work the same way:\n```\nturkle-client batches progress --id 17\nturkle-client batches input --id 17\nturkle-client batches results --id 17\n```\n\nAdding tasks to a batch can be done by passing the path to a csv file:\n```\nturkle-client batches add_tasks --id 3 --file new_tasks.csv\n```\n\n### Permissions\nProjects and batches can be limited to certain users or groups.\nThese permissions can be retrieved, added to, and replaced.\nThe dictionary to add or replace permissions looks like this:\n```\n{\"users\": [2, 3], \"groups\": []}\n```\nAll the methods require a project or batch id passed with `--pid` or `--bid`.\nThe add and replace methods require an additional file argument:\n```\nturkle-client permissions replace --pid 4 --file new_perms.json\n```\n\n## Library\nThe library is primarily a wrapper around the REST API of Turkle.\nTo use it, import the `Client` class and pass the url of the site and a token\nto initialize it.\n```\nimport turkle_client as tc\n\nclient = tc.Client(\"https://example.org\", \"abcdefghijkl\")\n```\nEach section of the API (users, groups, projects, batches, and permissions)\nhas its own object available from the client:\n```\nusers = client.users.list()\n```\nThe client methods expect json dictionaries as input.\nTo create a new user, pass a dictionary with at least a username and password:\n```\nnew_user = client.users.create({\n    \"username\": \"testuser\",\n    \"password\": \"password\"\n})\n```\n\n### Dynamic Batches\nNormally, batches are fixed when they are created, but the API adds support\nfor adding tasks.\nA dictionary with the batch id and a string with the csv fields including headers\nare passed to `add_tasks()`:\n```\nwith open(file_path, 'r') as file:\n    csv_content = file.read()\n    client.batches.add_tasks({\n        'id': batch_id,\n        'csv_text': csv_content\n    })\n```\n\nThe library provides a `BatchMonitor` that could support an active learning workflow.\nIt polls the `progress` function of a batch and returns when a goal has been reached:\n```\ndef goal_fn(progress):\n    percent = progress[\"total_finished_tasks\"] / progress[\"total_tasks\"]\n    return percent \u003e 0.75\n\ndef on_goal_reached(progress):\n    # add additional tasks here\n    print(\"Batch is 75% complete\")\n\nmonitor = tc.BatchMonitor(\n    client=client,\n    batch_id=3,\n    goal_fn=goal_fn,\n    callback_fn=on_goal_reached,\n    interval=10\n)\n\nmonitor.wait()\n```\n\n## Developers\n\n### Installing\n```\npip install -e .[dev]\n```\n\n### Testing\n```\npytest\n```\n\n### Releasing\n1. Update the version in __version__.py\n2. Update the changelog\n3. Create git tag\n4. Upload to PyPI\n    * rm -rf dist/ build/ *.egg-info/\n    * python -m build\n    * twine upload dist/*","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhltcoe%2Fturkle-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhltcoe%2Fturkle-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhltcoe%2Fturkle-client/lists"}