surge-api 1.5.7__tar.gz

surge-api-1.5.7/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Surge
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

surge-api-1.5.7/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.1
+Name: surge-api
+Version: 1.5.7
+Summary: Surge Python SDK
+Home-page: https://github.com/surge-ai/surge-python
+Author: Surge
+Author-email: team@surgehq.ai
+License: MIT
+Description: # 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
+        ```
+        
+Platform: UNKNOWN
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown

surge-api-1.5.7/README.md

@@ -0,0 +1,160 @@
+# 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
+```

surge-api-1.5.7/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

surge-api-1.5.7/setup.py

@@ -0,0 +1,23 @@
+from setuptools import setup, find_packages
+
+VERSION = '1.5.7'
+
+with open('requirements.txt') as f:
+    requirements = f.read().splitlines()
+
+with open('README.md', 'r') as fh:
+    long_description = fh.read()
+
+setup(name='surge-api',
+      version=VERSION,
+      description='Surge Python SDK',
+      author='Surge',
+      author_email='team@surgehq.ai',
+      url='https://github.com/surge-ai/surge-python',
+      license='MIT',
+      long_description=long_description,
+      long_description_content_type='text/markdown',
+      python_requires='>=3.6',
+      packages=find_packages(exclude=['tests', 'tests.*']),
+      install_requires=requirements,
+      tests_require=['pytest >= 6.0.0'])

surge-api-1.5.7/surge/__init__.py

@@ -0,0 +1,9 @@
+import os
+
+from surge.projects import Project
+from surge.tasks import Task
+from surge.teams import Team
+from surge.reports import Report
+
+api_key = os.environ.get("SURGE_API_KEY", None)
+base_url = os.environ.get("SURGE_BASE_URL", "https://app.surgehq.ai/api")

surge-api-1.5.7/surge/api_resource.py

@@ -0,0 +1,99 @@
+import requests
+
+import surge
+from surge.errors import SurgeRequestError, SurgeMissingAPIKeyError
+
+PROJECTS_ENDPOINT = "projects"
+TASKS_ENDPOINT = "tasks"
+REPORTS_ENDPOINT = "projects"
+QUESTIONS_ENDPOINT = "items"
+TEAMS_ENDPOINT = "teams"
+
+
+class APIResource(object):
+
+    def __init__(self, id=None):
+        self.id = id
+
+    def print_attrs(self, forbid_list: list = []):
+        return " ".join(
+            [f'{k}="{v}"' for k, v in self.__dict__.items() if not k in forbid_list]
+        )
+
+    @classmethod
+    def _base_request(cls, method, api_endpoint, params=None, api_key=None):
+        api_key_to_use = api_key or surge.api_key
+        if api_key_to_use is None:
+            raise SurgeMissingAPIKeyError
+
+        try:
+            url = f"{surge.base_url}/{api_endpoint}"
+
+            # GET request
+            if method == "get":
+                response = requests.get(url, auth=(api_key_to_use, ""), params=params)
+
+            # POST request
+            elif method == "post":
+                response = requests.post(url, auth=(api_key_to_use, ""), json=params)
+
+            # PUT request
+            elif method == "put":
+                if params is not None and len(params):
+                    response = requests.put(url, auth=(api_key_to_use, ""), data=params)
+                else:
+                    response = requests.put(url, auth=(api_key_to_use, ""))
+
+            elif method == "delete":
+                response = requests.delete(url, auth=(api_key_to_use, ""))
+
+            else:
+                raise SurgeRequestError("Invalid HTTP method.")
+
+            # Raise exception if there is an http error
+            response.raise_for_status()
+
+            # If no errors, return response as json
+            return response.json()
+
+        except requests.exceptions.HTTPError as err:
+            message = err.args[0]
+            message = f"{message}. {err.response.text}"
+            raise SurgeRequestError(message) from None
+
+        except requests.exceptions.JSONDecodeError as err:
+            message = err.args[0]
+            raise SurgeRequestError(message) from None
+
+        except Exception:
+            # Generic exception handling
+            raise SurgeRequestError
+
+    @classmethod
+    def get(cls, api_endpoint, params=None, api_key=None):
+        method = "get"
+        return cls._base_request(method,
+                                 api_endpoint,
+                                 params=params,
+                                 api_key=api_key)
+
+    @classmethod
+    def post(cls, api_endpoint, params=None, api_key=None):
+        method = "post"
+        return cls._base_request(method,
+                                 api_endpoint,
+                                 params=params,
+                                 api_key=api_key)
+
+    @classmethod
+    def put(cls, api_endpoint, params=None, api_key=None):
+        method = "put"
+        return cls._base_request(method,
+                                 api_endpoint,
+                                 params=params,
+                                 api_key=api_key)
+
+    @classmethod
+    def delete_request(cls, api_endpoint, api_key=None):
+        method = "delete"
+        return cls._base_request(method, api_endpoint, api_key=api_key)

surge-api-1.5.7/surge/carousel.py

@@ -0,0 +1,35 @@
+import json
+
+
+class Carousel(object):
+
+    def __init__(self, carousel_type=None):
+        self.carousel_type = carousel_type
+
+    def to_dict(self):
+        return self.__dict__
+
+    def to_json(self):
+        return json.dumps(self.to_dict())
+
+
+class BoundedRoundsCarousel(Carousel):
+
+    def __init__(self, min_rounds_for_carousel=1, max_rounds_for_carousel=1):
+        super().__init__(carousel_type="bounded_rounds")
+        self.min_rounds_for_carousel = min_rounds_for_carousel
+        self.max_rounds_for_carousel = max_rounds_for_carousel
+
+
+class DataKeyCarousel(Carousel):
+
+    def __init__(self, carousel_data_key=None):
+        super().__init__(carousel_type="data_key")
+        self.carousel_data_key = carousel_data_key
+
+
+class OrdinalColumnsCarousel(Carousel):
+
+    def __init__(self, max_rounds_for_carousel=1):
+        super().__init__(carousel_type="ordinal_columns")
+        self.max_rounds_for_carousel = max_rounds_for_carousel

surge-api-1.5.7/surge/errors.py

@@ -0,0 +1,52 @@
+class SurgeRequestError(Exception):
+    """Catch-all exception for errors that occur when making a request"""
+
+    def __init__(self, message="Something went wrong with the API request."):
+        self.message = message
+        super().__init__(self.message)
+
+
+class SurgeMissingAPIKeyError(Exception):
+    """Raise when user has not set their API key"""
+
+    def __init__(self, message="Surge API key has not been set."):
+        self.message = message
+        super().__init__(self.message)
+
+
+class SurgeMissingIDError(Exception):
+    """Raise when a Surge object is missing an ID"""
+
+    def __init__(self, message="Must be initialized with an id."):
+        self.message = message
+        super().__init__(self.message)
+
+
+class SurgeMissingAttributeError(Exception):
+    """Raise when a Surge object is missing a required attribute"""
+
+    def __init__(self, message="Object is missing a required attribute."):
+        self.message = message
+        super().__init__(self.message)
+
+
+class SurgeProjectQuestionError(Exception):
+    """Raise for exceptions that occur when adding Questions to a new Project"""
+
+    def __init__(
+            self,
+            message="All questions added to a Project must be of type Question."
+    ):
+        self.message = message
+        super().__init__(self.message)
+
+
+class SurgeTaskDataError(Exception):
+    """Raise for exceptions that occur when creating Task objects"""
+
+    def __init__(
+        self,
+        message="Invalid argument: task_data must be a non-empty list of dicts."
+    ):
+        self.message = message
+        super().__init__(self.message)