initial commit

Author: Keith Ingersoll

.gitattributes

@@ -0,0 +1 @@
+civis/tests/cassettes/*.yaml -diff

.gitignore

@@ -0,0 +1,43 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+eggs/
+.eggs/
+parts/
+sdist/
+*.egg-info/
+*.egg
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*,cover
+
+# Django stuff:
+*.log
+
+# Internal
+swagger.json
+
+# vim
+*.swp
+
+# Sphinx docs
+docs/source/generated/
+docs/source/api_resources.rst

.gitmodules

@@ -0,0 +1,6 @@
+[submodule "docs/sphinxext"]
+	path = docs/sphinxext
+	url = https://github.com/numpy/numpydoc
+[submodule "docs/sphinx_rtd_theme"]
+	path = docs/sphinx_rtd_theme
+	url = https://github.com/snide/sphinx_rtd_theme.git

.travis.yml

@@ -0,0 +1,14 @@
+language: python
+python:
+    - "3.4"
+install:
+    - pip install -r requirements.txt
+    - pip install -r dev-requirements.txt
+    - pip install -e .
+env:
+  global:
+    - CIVIS_API_KEY=FOOBAR
+before_script: flake8 civis
+script:
+    - py.test --cov civis
+    - sphinx-build -b html -nW docs/source/ docs/build/

CHANGELOG.md

@@ -0,0 +1,8 @@
+# Change Log
+All notable changes to this project will be documented in this file.
+This project adheres to [Semantic Versioning](http://semver.org/).
+
+
+## 1.0.0 - 2016-11-07
+### Added
+- Initial release

CODE_OF_CONDUCT.md

@@ -0,0 +1,50 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, and in the interest of
+fostering an open and welcoming community, we pledge to respect all people who
+contribute through reporting issues, posting feature requests, updating
+documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free
+experience for everyone, regardless of level of experience, gender, gender
+identity and expression, sexual orientation, disability, personal appearance,
+body size, race, ethnicity, age, religion, or nationality.
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery
+* Personal attacks
+* Trolling or insulting/derogatory comments
+* Public or private harassment
+* Publishing other's private information, such as physical or electronic
+  addresses, without explicit permission
+* Other unethical or unprofessional conduct
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+By adopting this Code of Conduct, project maintainers commit themselves to
+fairly and consistently applying these principles to every aspect of managing
+this project. Project maintainers who do not follow or enforce the Code of
+Conduct may be permanently removed from the project team.
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting a project maintainer at [email protected].
+All complaints will be reviewed and investigated and will result in a response
+that is deemed necessary and appropriate to the circumstances. Maintainers are
+obligated to maintain confidentiality with regard to the reporter of an
+incident.
+
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 1.3.0, available at
+[http://contributor-covenant.org/version/1/3/0/][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/3/0/

CONTRIBUTING.md

@@ -0,0 +1,32 @@
+# Contributing to civis-python
+
+We welcome bug reports and pull requests from everyone!
+This project is intended to be a safe, welcoming space for collaboration, and
+contributors are expected to adhere to the
+[Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+
+## Getting Started
+
+1. Fork it ( https://github.com/civisanalytics/civis-python/fork ).
+2. Install it, with the development dependencies.  See `README.md`.
+3. Make sure you are able to run the test suite locally (`py.test civis`).
+4. Create a feature branch (`git checkout -b my-new-feature`).
+5. Make your change. Don't forget tests.
+6. Make sure the test suite, including your new tests, passes
+   (`py.test civis && flake8 civis`).
+7. Commit your changes (`git commit -am 'Add some feature'`).
+8. Push to the branch (`git push origin my-new-feature`).
+9. Create a new pull request.
+10. If the build fails, address any issues.
+
+## Tips
+
+- All pull requests must include test coverage. If you’re not sure how to test
+  your changes, feel free to ask for help.
+- Contributions must conform to the guidelines encoded by `flake8`, based on
+  PEP-8.
+- Don’t forget to add your change to the [CHANGELOG](CHANGELOG.md). See
+  [Keep a CHANGELOG](http://keepachangelog.com/) for guidelines.
+
+Thank you for taking the time to contribute!

LICENSE.md

@@ -0,0 +1,27 @@
+Copyright (c) 2016, Civis Analytics
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

MANIFEST.in

@@ -0,0 +1,4 @@
+include requirements.txt
+include README.md
+include LICENSE.md
+include civis/_version.py

README.md

@@ -0,0 +1,66 @@
+Civis API Python Client
+=======================
+
+# Introduction
+
+The Civis API Python client is a Python package that helps analysts and
+developers interact with the Civis Platform. The package includes a set of
+tools around common workflows as well as a convenient interface to make
+requests directly to the Civis API. See the
+[full documentation](https://civis-python.readthedocs.io) for more details.
+
+
+# Installation
+
+1. Get a Civis API key [(instructions)](https://civis.zendesk.com/hc/en-us/articles/216341583-Generating-an-API-Key)
+2. Add a `CIVIS_API_KEY` environment variable.
+3. You can add the following to `.bash_profile` for bash
+    ```
+    export CIVIS_API_KEY="alphaNumericApiK3y"
+    ```
+4. Source your `.bash_profile`
+5. Install the package
+
+    ```
+    pip install git+git://github.com/civisanalytics/civis-python.git
+    ```
+6. Optionally, install `pandas` to enable some functionality in `civis-python`
+
+    ```
+    pip install pandas
+    ```
+
+# Usage
+
+`civis-python` includes a number of wrappers around the Civis API for
+common workflows.
+
+```python
+import civis
+df = civis.io.read_civis(table="my_schema.my_table",
+                         database="database",
+                         use_pandas=True)
+```
+
+The Civis API may also be directly accessed via the `APIClient` class.
+
+```python
+import civis
+client = civis.APIClient()
+database = client.databases.list()
+```
+
+See the [full documentation](https://civis-python.readthedocs.io) for a more
+complete user guide.
+
+
+# Contributing
+
+See `CONTIBUTING.md` for information about contributing to this project.
+
+
+# License
+
+BSD-3
+
+See `LICENSE.md` for details.

civis/__init__.py

@@ -0,0 +1,5 @@
+from ._version import __version__
+from .civis import APIClient, find, find_one
+from . import io
+
+__all__ = ["__version__", "APIClient", "find", "find_one", "io"]

civis/_utils.py

@@ -0,0 +1,22 @@
+import re
+import uuid
+
+
+UNDERSCORER1 = re.compile(r'(.)([A-Z][a-z]+)')
+UNDERSCORER2 = re.compile('([a-z0-9])([A-Z])')
+
+
+def maybe_get_random_name(name):
+    if not name:
+        name = uuid.uuid4().hex
+    return name
+
+
+def camel_to_snake(word):
+    # https://gist.github.com/jaytaylor/3660565
+    word = UNDERSCORER1.sub(r'\1_\2', word)
+    return UNDERSCORER2.sub(r'\1_\2', word).lower()
+
+
+def to_camelcase(s):
+    return re.sub(r'(^|_)([a-zA-Z])', lambda m: m.group(2).upper(), s)

civis/_version.py

@@ -0,0 +1 @@
+__version__ = "1.0.0"

civis/base.py

@@ -0,0 +1,89 @@
+from posixpath import join
+import threading
+
+from civis.response import PaginatedResponse, convert_response_data_type
+
+
+def tostr_urljoin(*x):
+    return join(*map(str, x))
+
+
+class CivisJobFailure(Exception):
+    def __init__(self, err_msg, response=None):
+        self.error_message = err_msg
+        self.response = response
+
+    def __str__(self):
+        return self.error_message
+
+
+class CivisAPIError(Exception):
+    def __init__(self, response):
+        if response.content:  # the API itself gave an error response
+            json = response.json()
+            self.error_message = json["errorDescription"]
+        else:  # this was something like a 502
+            self.error_message = response.reason
+
+        self.status_code = response.status_code
+        self._response = response
+
+    def __str__(self):
+        if self.status_code:
+            return "({}) {}".format(self.status_code, self.error_message)
+        else:
+            return self.error_message
+
+
+class EmptyResultError(Exception):
+    pass
+
+
+class CivisAPIKeyError(Exception):
+    pass
+
+
+class Endpoint:
+
+    _base_url = "https://api.civisanalytics.com/"
+    _lock = threading.Lock()
+
+    def __init__(self, session, return_type='civis'):
+        self._session = session
+        self._return_type = return_type
+
+    def _build_path(self, path):
+        if not path:
+            return self._base_url
+        return tostr_urljoin(self._base_url, path.strip("/"))
+
+    def _make_request(self, method, path=None, params=None, data=None,
+                      **kwargs):
+        url = self._build_path(path)
+
+        with self._lock:
+            response = self._session.request(method, url, json=data,
+                                             params=params, **kwargs)
+
+        if response.status_code in [204, 205]:
+            return
+
+        if response.status_code == 401:
+            auth_error = response.headers["www-authenticate"]
+            raise CivisAPIKeyError(auth_error) from CivisAPIError(response)
+
+        if not response.ok:
+            raise CivisAPIError(response)
+
+        return response
+
+    def _call_api(self, method, path=None, params=None, data=None, **kwargs):
+        iterator = kwargs.pop('iterator', False)
+
+        if iterator:
+            return PaginatedResponse(path, params, self)
+        else:
+            resp = self._make_request(method, path, params, data, **kwargs)
+            resp = convert_response_data_type(resp,
+                                              return_type=self._return_type)
+            return resp