# Surge Python SDK
The Surge Python SDK provides convenient access to the Surge API from applications written in the Python language.
## Installation
Install this package by using pip:
```bash
pip install --upgrade surge-api
```
### Requirements
* Python 3.6+
## Usage
Documentation and and examples are available [here](https://app.surgehq.ai/docs/api#).
### Authentication
The library needs to be configured with your account's API key which is available in your Surge Profile. Set `surge.api_key` to its value:
```python
import surge
surge.api_key = "YOUR API KEY"
```
Or set the API key as an environment variable:
```bash
export SURGE_API_KEY=<YOUR API KEY>
```
### Projects
Once the API key has been set, you can list all of the Projects under your Surge account or retrieve a specific Project by its ID.
```python
# List your Projects
projects = surge.Project.list()
# Print the name of the first Project
print(projects[0].name)
# Retrieve a specific Project
project = surge.Project.retrieve("076d207b-c207-41ca-b73a-5822fe2248ab")
# print the number of tasks in that Project
print(project.num_tasks)
```
If you have an existing project, you can use it as a template to get a new batch of data annotated.
You can add new labeling tasks from a CSV or with a list of dictionaries.
```python
# Create a project from a template
template_project_id = "076d207b-c207-41ca-b73a-5822fe2248ab"
project = surge.Project.create("My Labeling Project (July 2023 Batch)", template_id=template_project_id)
# Add data from a CSV file
project.create_tasks_from_csv('my_data.csv')
# Or add data directly
tasks = project.create_tasks([{
"company": "Surge",
"city": "San Francisco",
"state": "CA"
}])
# Launch the project to send it to the Surge workforce
project.launch()
```
Or you can create a new project from scratch by creating your own template and list of Question:
```python
from surge.questions import FreeResponseQuestion, MultipleChoiceQuestion, CheckboxQuestion
# Create a new Project
free_response_q = FreeResponseQuestion(
text="What is this company's website?",
label="")
multiple_choice_q = MultipleChoiceQuestion(
text="What category does this company belong to?",
label="Category",
options=["Tech", "Sports", "Gaming"])
checkbox_q = CheckboxQuestion(
text="Check all the social media accounts this company has",
label="",
options=["Facebook", "Twitter", "Pinterest", "Google+"])
fields_template_text = '''
<p>Company: {{company}}</p>
'''
project = surge.Project.create(
name="Categorize this company",
instructions="You will be asked to categorize a company.",
questions=[free_response_q, multiple_choice_q, checkbox_q],
callback_url="https://customer-callback-url/",
fields_template=fields_template_text,
num_workers_per_task=3)
```
### Tasks
You can create new Tasks for a project, list all of the Tasks in a given project, or retrieve a specific Task given its ID.
```python
# Create Tasks for the new Project
tasks_data = [{"id": 1, "company": "Surge AI"}, {"id": 2, "company":"Twitch TV"}]
tasks = project.create_tasks(tasks_data)
# List all Tasks in the Project
all_tasks = project.list_tasks()
# Retrieve a specific Task
task = surge.Task.retrieve(task_id = "eaa44610-c8f6-4480-b746-28b6c8defd4d")
# Print the fields of that Task
print(task.fields)
```
You can also create Tasks in bulk by uploading a local CSV file. The header of the CSV file must specify the fields that are used in your Tasks.
| id | company |
| :--- | :----: |
| 1 | Surge AI |
| 2 | Twitch TV |
```python
# Create Tasks in bulk via CSV file
file_path = "./companies_to_classify.csv"
tasks = project.create_tasks_from_csv(file_path)
```
## Development
The test suite depends on `pytest`, which you can install using pip:
```bash
pip install pytest
```
To run tests from the command line:
```bash
# Run all tests
pytest
# Run tests in a specific file
pytest tests/test_projects.py
# Run a specific test
pytest tests/test_projects.py::test_init_complete
```
Raw data
{
"_id": null,
"home_page": "https://github.com/surge-ai/surge-python",
"name": "surge-api",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": null,
"author": "Surge",
"author_email": "team@surgehq.ai",
"download_url": null,
"platform": null,
"description": "# Surge Python SDK\n\nThe Surge Python SDK provides convenient access to the Surge API from applications written in the Python language.\n\n## Installation\n\nInstall this package by using pip:\n\n```bash\npip install --upgrade surge-api\n```\n\n### Requirements\n\n* Python 3.6+\n\n## Usage\n\nDocumentation and and examples are available [here](https://app.surgehq.ai/docs/api#).\n\n### Authentication\n\nThe library needs to be configured with your account's API key which is available in your Surge Profile. Set `surge.api_key` to its value:\n\n```python\nimport surge\nsurge.api_key = \"YOUR API KEY\"\n```\nOr set the API key as an environment variable:\n\n```bash\nexport SURGE_API_KEY=<YOUR API KEY>\n```\n\n### Projects\n\nOnce the API key has been set, you can list all of the Projects under your Surge account or retrieve a specific Project by its ID.\n\n```python\n# List your Projects\nprojects = surge.Project.list()\n\n# Print the name of the first Project\nprint(projects[0].name)\n\n# Retrieve a specific Project\nproject = surge.Project.retrieve(\"076d207b-c207-41ca-b73a-5822fe2248ab\")\n\n# print the number of tasks in that Project\nprint(project.num_tasks)\n```\nIf you have an existing project, you can use it as a template to get a new batch of data annotated.\nYou can add new labeling tasks from a CSV or with a list of dictionaries.\n\n```python\n# Create a project from a template\ntemplate_project_id = \"076d207b-c207-41ca-b73a-5822fe2248ab\"\nproject = surge.Project.create(\"My Labeling Project (July 2023 Batch)\", template_id=template_project_id)\n\n# Add data from a CSV file\nproject.create_tasks_from_csv('my_data.csv')\n\n# Or add data directly\ntasks = project.create_tasks([{\n \"company\": \"Surge\",\n \"city\": \"San Francisco\",\n \"state\": \"CA\"\n}])\n\n# Launch the project to send it to the Surge workforce\nproject.launch()\n```\n\n\nOr you can create a new project from scratch by creating your own template and list of Question:\n\n```python\nfrom surge.questions import FreeResponseQuestion, MultipleChoiceQuestion, CheckboxQuestion\n\n# Create a new Project\nfree_response_q = FreeResponseQuestion(\n text=\"What is this company's website?\",\n label=\"\")\n\nmultiple_choice_q = MultipleChoiceQuestion(\n text=\"What category does this company belong to?\",\n label=\"Category\",\n options=[\"Tech\", \"Sports\", \"Gaming\"])\n\ncheckbox_q = CheckboxQuestion(\n text=\"Check all the social media accounts this company has\",\n label=\"\",\n options=[\"Facebook\", \"Twitter\", \"Pinterest\", \"Google+\"])\n\nfields_template_text = '''\n <p>Company: {{company}}</p>\n'''\n\nproject = surge.Project.create(\n name=\"Categorize this company\",\n instructions=\"You will be asked to categorize a company.\",\n questions=[free_response_q, multiple_choice_q, checkbox_q],\n callback_url=\"https://customer-callback-url/\",\n fields_template=fields_template_text,\n num_workers_per_task=3)\n```\n\n### Tasks\n\nYou can create new Tasks for a project, list all of the Tasks in a given project, or retrieve a specific Task given its ID.\n\n```python\n# Create Tasks for the new Project\ntasks_data = [{\"id\": 1, \"company\": \"Surge AI\"}, {\"id\": 2, \"company\":\"Twitch TV\"}]\ntasks = project.create_tasks(tasks_data)\n\n# List all Tasks in the Project\nall_tasks = project.list_tasks()\n\n# Retrieve a specific Task\ntask = surge.Task.retrieve(task_id = \"eaa44610-c8f6-4480-b746-28b6c8defd4d\")\n\n# Print the fields of that Task\nprint(task.fields)\n```\n\nYou can also create Tasks in bulk by uploading a local CSV file. The header of the CSV file must specify the fields that are used in your Tasks.\n\n| id | company |\n| :--- | :----: |\n| 1 | Surge AI |\n| 2 | Twitch TV |\n\n```python\n# Create Tasks in bulk via CSV file\nfile_path = \"./companies_to_classify.csv\"\ntasks = project.create_tasks_from_csv(file_path)\n```\n\n\n## Development\n\nThe test suite depends on `pytest`, which you can install using pip:\n\n```bash\npip install pytest\n```\n\nTo run tests from the command line:\n\n```bash\n# Run all tests\npytest\n\n# Run tests in a specific file\npytest tests/test_projects.py\n\n# Run a specific test\npytest tests/test_projects.py::test_init_complete\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Surge Python SDK",
"version": "1.5.11",
"project_urls": {
"Homepage": "https://github.com/surge-ai/surge-python"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b0d212984300f6bd3a38e2cdf4e4668b5c76c9a8bb127cfd8921e31fa6ff5c6a",
"md5": "79e533e94f33e22005add3b2cd1ed3da",
"sha256": "e29925f3cebc319166585f1b82ec555a43eac0df99709fe1df0bfef86694a185"
},
"downloads": -1,
"filename": "surge_api-1.5.11-py3-none-any.whl",
"has_sig": false,
"md5_digest": "79e533e94f33e22005add3b2cd1ed3da",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 19061,
"upload_time": "2024-10-31T18:06:27",
"upload_time_iso_8601": "2024-10-31T18:06:27.941879Z",
"url": "https://files.pythonhosted.org/packages/b0/d2/12984300f6bd3a38e2cdf4e4668b5c76c9a8bb127cfd8921e31fa6ff5c6a/surge_api-1.5.11-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-31 18:06:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "surge-ai",
"github_project": "surge-python",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"circle": true,
"requirements": [],
"lcname": "surge-api"
}
JSON
