{"id":23209164,"url":"https://github.com/algorithmiaio/algorithmia-python","last_synced_at":"2025-04-04T18:10:31.795Z","repository":{"id":34788433,"uuid":"38772089","full_name":"algorithmiaio/algorithmia-python","owner":"algorithmiaio","description":"Python Client for Algorithmia Algorithms and Data API","archived":false,"fork":false,"pushed_at":"2024-02-05T17:54:50.000Z","size":360,"stargazers_count":138,"open_issues_count":9,"forks_count":39,"subscribers_count":32,"default_branch":"develop","last_synced_at":"2024-04-26T13:22:39.337Z","etag":null,"topics":["algorithmia","algorithms","api","machine-learning","python"],"latest_commit_sha":null,"homepage":"https://algorithmia.com","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/algorithmiaio.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":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-07-08T18:25:17.000Z","updated_at":"2024-06-18T20:09:46.956Z","dependencies_parsed_at":"2024-06-18T20:09:45.129Z","dependency_job_id":"d332063c-d068-466a-9f64-8a510305e5b0","html_url":"https://github.com/algorithmiaio/algorithmia-python","commit_stats":{"total_commits":225,"total_committers":20,"mean_commits":11.25,"dds":0.7777777777777778,"last_synced_commit":"31f0e9047483bea72b4fdec9ef42b9174b2aa2dc"},"previous_names":[],"tags_count":39,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/algorithmiaio%2Falgorithmia-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/algorithmiaio%2Falgorithmia-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/algorithmiaio%2Falgorithmia-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/algorithmiaio%2Falgorithmia-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/algorithmiaio","download_url":"https://codeload.github.com/algorithmiaio/algorithmia-python/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247226215,"owners_count":20904465,"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":["algorithmia","algorithms","api","machine-learning","python"],"created_at":"2024-12-18T18:15:00.431Z","updated_at":"2025-04-04T18:10:31.764Z","avatar_url":"https://github.com/algorithmiaio.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"Algorithmia Common Library (python)\n===================================\n\nPython client library for accessing the Algorithmia API\nFor API documentation, see the [PythonDocs](https://algorithmia.com/docs/lang/python)\n\n[![PyPI](https://img.shields.io/pypi/v/algorithmia.svg?maxAge=600)]()\n\n## Algorithm Development Kit\nThis package contains the [algorithmia-adk](https://github.com/algorithmiaio/algorithmia-adk-python) development kit, simply add `from Algorithmia import ADK` into your workflow to access it.\n\n## Install from PyPi\n\nThe official Algorithmia python client is [available on PyPi](https://pypi.python.org/pypi/algorithmia).\nInstall it with pip:\n\n```bash\npip install algorithmia\n```\n\n## Install from source\n\nBuild algorithmia client wheel:\n\n```bash\npython setup.py bdist_wheel\n```\n\nInstall a wheel manually:\n\n```bash\npip install --user --upgrade dist/algorithmia-*.whl\n```\n#install locally for testing\n\nfrom directory containing setup.py and the Algorithmia directory:\n```bash\npip3 install ./\n```\n#add CLI script to PATH\n\nto use the CLI it may be nessesary to add the install location to the PATH enviroment variable\n```bash\nexport PATH = $HOME/.local/bin:$PATH\n```\n\n## Authentication\n\nFirst, create an Algorithmia client and authenticate with your API key:\n\n```python\nimport Algorithmia\n\napiKey = '{{Your API key here}}'\nclient = Algorithmia.client(apiKey)\n```\n\nNow you're ready to call algorithms.\n\n## Calling algorithms\n\nThe following examples of calling algorithms are organized by type of input/output which vary between algorithms.\n\nNote: a single algorithm may have different input and output types, or accept multiple types of input,\nso consult the algorithm's description for usage examples specific to that algorithm.\n\n### Text input/output\n\nCall an algorithm with text input by simply passing a string into its `pipe` method.\nIf the algorithm output is text, then the `result` field of the response will be a string.\n\n```python\nalgo = client.algo('demo/Hello/0.1.1')\nresponse = algo.pipe(\"HAL 9000\")\nprint(response.result)    # Hello, world!\nprint(response.metadata)  # Metadata(content_type='text',duration=0.0002127)\nprint(response.metadata.duration) # 0.0002127\n```\n\n### JSON input/output\n\nCall an algorithm with JSON input by simply passing in a type that can be serialized to JSON:\nmost notably python dicts and arrays.\nFor algorithms that return JSON, the `result` field of the response will be the appropriate\ndeserialized type.\n\n```python\nalgo = client.algo('WebPredict/ListAnagrams/0.1.0')\nresult = algo.pipe([\"transformer\", \"terraforms\", \"retransform\"]).result\n# -\u003e [\"transformer\",\"retransform\"]\n```\n\n### Binary input/output\n\nCall an algorithm with Binary input by passing a byte array into the `pipe` method.\nSimilarly, if the algorithm response is binary data, then the `result` field of the response\nwill be a byte array.\n\n```python\ninput = bytearray(open(\"/path/to/bender.png\", \"rb\").read())\nresult = client.algo(\"opencv/SmartThumbnail/0.1\").pipe(input).result\n# -\u003e [binary byte sequence]\n```\n\n### Error handling\n\nAPI errors and Algorithm exceptions will result in calls to `pipe` throwing an `AlgoException`:\n\n```python\nclient.algo('util/whoopsWrongAlgo').pipe('Hello, world!')\n# Algorithmia.algo_response.AlgoException: algorithm algo://util/whoopsWrongAlgo not found\n```\n\n### Request options\n\nThe client exposes options that can configure algorithm requests.\nThis includes support for changing the timeout or indicating that the API should include stdout in the response.\n\n```python\nfrom Algorithmia.algorithm import OutputType\nresponse = client.algo('util/echo').set_options(timeout=60, stdout=False)\nprint(response.metadata.stdout)\n```\n\nNote: `stdout=True` is only supported if you have access to the algorithm source.\n\n\n## Working with data\nThe Algorithmia client also provides a way to manage both Algorithmia hosted data\nand data from Dropbox or S3 accounts that you've connected to you Algorithmia account.\n\n### Create directories\nCreate directories by instantiating a `DataDirectory` object and calling `create()`:\n\n```python\nclient.dir(\"data://.my/foo\").create()\nclient.dir(\"dropbox://somefolder\").create()\n```\n\n### Upload files to a directory\n\nUpload files by calling `put` on a `DataFile` object,\nor by calling `putFile` on a `DataDirectory` object.\n\n```python\nfoo = client.dir(\"data://.my/foo\")\nfoo.file(\"remote_file\").putFile(\"/path/to/myfile\")\nfoo.file(\"sample.txt\").put(\"sample text contents\")\nfoo.file(\"binary_file\").put(some_binary_data)\n```\n\nNote: you can instantiate a `DataFile` by either `client.file(path)` or `client.dir(path).file(filename)`\n\n\n### Download contents of file\n\nDownload files by calling `getString`, `getBytes`, `getJson`, or `getFile` on a `DataFile` object:\n\n```python\nfoo = client.dir(\"data://.my/foo\")\nsampleText = foo.file(\"sample.txt\").getString()  # String object\nbinaryContent = foo.file(\"binary_file\").getBytes()  # Binary data\ntempFile = foo.file(\"myfile\").getFile()   # Open file descriptor\n```\n\n### Delete files and directories\n\nDelete files and directories by calling `delete` on their respective `DataFile` or `DataDirectory` object.\nDataDirectories take an optional `force` parameter that indicates whether the directory should be deleted\nif it contains files or other directories.\n\n```python\nfoo = client.dir(\"data://.my/foo\")\nfoo.file(\"sample.txt\").delete()\nfoo.delete(true) // true implies force deleting the directory and its contents\n```\n\n\n### List directory contents\n\nIterate over the contents of a directory using the iterated returned by calling `list`, `files`, or `dirs`\non a `DataDirectory` object:\n\n```python\nfoo = client.dir(\"data://.my/foo\")\n\n# List files in \"foo\"\nfor file in foo.files():\n    print(file.path + \" at URL: \" + file.url + \" last modified \" + file.last_modified)\n\n# List directories in \"foo\"\nfor file in foo.dirs():\n    print(dir.path + \" at URL: \" + file.url)\n\n# List everything in \"foo\"\nfor entry in foo.list():\n    print(entry.path + \" at URL: \" + entry.url)\n```\n\n### Manage directory permissions\n\nDirectory permissions may be set when creating a directory, or may be updated on already existing directories.\n\n```python\nfrom Algorithmia.acl import ReadAcl, AclType\nfoo = client.dir(\"data://.my/foo\")\n# ReadAcl.public is a wrapper for Acl(AclType.public) to make things easier\nfoo.create(ReadAcl.public)\n\nacl = foo.get_permissions()  # Acl object\nacl.read_acl == AclType.public  # True\n\nfoo.update_permissions(ReadAcl.private)\nfoo.get_permissions().read_acl == AclType.private # True\n```\n\n# Algorithmia CLI\n\nAlgorithmia CLI is a cross-platform tool for interfacing with algorithms and the Algorithmia Data API.\n\n## Configure Authentication\n\nIn order to make calls with the CLI, you'll need to configure the authentication with an API key. If you don't already have an API key, get started by signing up for an account at [Algorithmia.com](https://algorithmia.com). Once you've completed the sign up process, copy the API key from your account dashboard.\n\nBegin the configuration process by running the command `algo auth`.\nYou will see an interactive prompt to guide you through setting up a default profile:\n\n```\n$ algo auth\nConfiguring authentication for profile: 'default'\nEnter API Endpoint [https://api.algorithmia.com]:\nEnter API Key:\n(optional) enter path to custom CA certificate:\nProfile is ready to use. Test with 'algo ls'\n```\n\nSee [Using multiple profiles](#using-multiple-profiles) for instructions on how to set authenticate and use more than one profile with the Algorithmia CLI tool.\n\n## Usage\n\nTo call an algorithm from the CLI, use the command syntax: `algo run`, followed by the algorithm’s username and algorithm name, the data options, and finally the input. Here is a basic example calling the [Factor algorithm](https://algorithmia.com/algorithms/kenny/Factor):\n\n```text\n$ algo run kenny/factor -d 19635\n[3,5,7,11,17]\n```\n\nRun `algo run --help` to see more command options or view the following [Options](#options) section.\n\n### Options\n\n#### Input Data Options\nThe Algorithmia CLI supports JSON, text, and binary data, as well as an option to auto-detect the data type.\n\n| Option Flag               | Description |\n| :------------             | :--------------- |\n| -d, --data \u003cdata\u003e         | If the data parses as JSON, assume JSON, else if the data is valid UTF-8, assume text, else assume binary |\n| -D, --data-file \u003cfile\u003e    | Same as --data, but the input data is read from a file |\n\nYou may also explictly specify the input type as text (`-t`/`-T`), json (`-j`/`-J`), or binary (`-b`/`-B`) instead of using the auto-detection (`-d`/`-D`).\n\n#### Output Options\n\nThe algorithm result is printed to STDOUT by defauft. Additional notices may be printed to STDERR. If you'd like to output the result to a file, use the output option flag followed by a filename:\n\n```text\n$ algo run kenny/factor -d 17 --output results.txt\n```\n\n| Option Flag     | Description |\n| :------------   |:--------------- |\n| --debug         | Print algorithm's STDOUT (author-only) |\n| -o, --output \u003cfile\u003e |  Print result to a file |\n\n#### Other Options\n\n| Option Flag     | Description |\n| :------------   |:--------------- |\n| --timeout \u003cseconds\u003e | Sets algorithm timeout\n\n#### Examples:\n\n```text\n$ algo run kenny/factor/0.1.0 -d '79'                   Run algorithm with specified version \u0026 data input\n$ algo run anowell/Dijkstra -D routes.json              Run algorithm with file input\n$ algo run anowell/Dijkstra -D - \u003c routes.json          Same as above but using STDIN\n$ algo run opencv/SmartThumbnail -D in.png -o out.png   Runs algorithm with binary files as input\n$ algo run kenny/factor -d 17 --timeout 2               Runs algorithm with a timeout of 2 seconds\n```\n\n\n## The Algorithmia Data API\n\nUse the Algorithmia CLI to interact with the Algorithmia Data API. You can use the CLI to create and manage your data directories.\n\n**Data commands include:**\n\n| Command   | Description |\n| :------------   |:--------------- |\n| ls |  List contents of a data directory |\n| mkdir | Create a data directory |\n| rmdir | Delete a data directory |\n| rm | Remove a file from a data directory |\n| cp | Copy file(s) to or from a data directory |\n| cat | Concatenate \u0026 print file(s) in a directory |\n\n### Examples of the Algorithmia Data API usage:\n\nCreate a data directory:\n```text\n$ algo mkdir .my/cuteAnimals\n\nCreated directory data://.my/cuteAnimals\n```\n\nCopy a file from your local directory to the new data directory:\n\n```text\n$ algo cp chubby_kittens.jpg data://.my/cuteAnimals\n\nUploaded data://.my/cuteAnimals/chubby_kittens.jpg\n```\n\n## Using multiple profiles\n\n### Add additional profiles\n\nWith the Algorithmia CLI, you can configure multiple custom profiles to use. To add a new profile, simply specify a profile to `algo auth` follow the same interactive prompt.\n\n```text\nalgo auth --profile second_user\nConfiguring authentication for profile: 'second_user'\nEnter API Endpoint [https://api.algorithmia.com]:\nEnter API Key:\n(optional) enter path to custom CA certificate:\n```\n\nNow you may use `algo ls --profile second_user` to list files in your `second_user` account. For more information, see the auth command help with `algo auth --help`.\n\n### Using profiles in commands\n\nWhen running commands, the Algorithmia CLI will use the default profile unless otherwise specified with the `--profile \u003cprofile\u003e` option. See the following example:\n\n```text\n$ algo run kenny/factor -d 17 --profile second_user\n[17]\n```\n\n\n\n# Running tests\n\nMake sure you have `numpy` installed before running `datafile_test.py`\n```bash\nexport ALGORITHMIA_API_KEY={{Your API key here}}\ncd Test\npython acl_test.py\npython algo_test.py\npython datadirectorytest.py\npython datafile_test.py\npython utiltest.py\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falgorithmiaio%2Falgorithmia-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falgorithmiaio%2Falgorithmia-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falgorithmiaio%2Falgorithmia-python/lists"}