Merge pull request #331 from pcattori/prefactor

Prefactor

.github/workflows/ci.yml

@@ -24,14 +24,14 @@ jobs:
     - name: Install dependencies
       run: poetry install
     - name: Run flake8
-      run: poetry run flake8 .
+      run: poetry run invoke lint
     - name: Run black
-      run: poetry run black --check .
+      run: poetry run invoke format
 
   Test:
     strategy:
       matrix:
-        python_version: ['3.6', '3.7', '3.8']
+        python_version: [3.6, 3.7, 3.8]
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v1
@@ -44,7 +44,7 @@ jobs:
     - name: Install dependencies
       run: poetry install
     - name: Run pytest
-      run: poetry run pytest
+      run: poetry run invoke test
 
   Docs:
     runs-on: ubuntu-latest
@@ -59,4 +59,4 @@ jobs:
     - name: Install dependencies
       run: poetry install
     - name: Build docs
-      run: poetry run sphinx-build -b html docs docs/_build -W
+      run: poetry run invoke docs

docs/conf.py

@@ -61,7 +61,7 @@
 autosectionlabel_prefix_document = True
 intersphinx_mapping = {
     "https://docs.python.org/": None,
-    "requests": ("https://requests.kennethreitz.org/en/master/", None),
+    "requests": ("https://requests.readthedocs.io/en/master/", None),
     "pandas": ("https://pandas.pydata.org/pandas-docs/stable", None),
 }
 

docs/contributor-guide.md

@@ -0,0 +1,10 @@
+# Contributor guide
+
+  * [Bug Reports and Feature Requests](contributor-guide/bugs-and-features)
+  * [Code Migrations](contributor-guide/migration)
+  * [Configure your Text Editor](contributor-guide/config-text-editor)
+  * [Install](contributor-guide/install)
+  * [Navigating Inheritance](contributor-guide/navigating-inheritance)
+  * [Pull Requests](contributor-guide/pull-request)
+  * [Run and Build](contributor-guide/run-and-build)
+  * [Toolchain](contributor-guide/toolchain)

docs/contributor-guide/bugs-and-features.md

@@ -0,0 +1,10 @@
+# 🐛 Bug Reports & 🙋 Feature Requests
+
+Please leave bug reports and feature requests as [Github issues](https://github.com/Datatamer/tamr-client/issues/new/choose) .
+
+---
+
+Be sure to check through existing issues (open and closed) to confirm that the bug hasn’t been reported before.
+
+Duplicate bug reports are a huge drain on the time of other contributors, and
+should be avoided as much as possible.

docs/contributor-guide/config-text-editor.md

@@ -0,0 +1,5 @@
+# Configure your Text Editor
+
+- [Atom](https://atom.io/)
+  - [python-black](https://atom.io/packages/python-black)
+  - [linter-flake8](https://atom.io/packages/linter-flake8)

docs/contributor-guide/install.md

@@ -0,0 +1,32 @@
+# Install
+
+This project uses `pyenv` and `poetry`.
+If you do not have these installed, checkout the [toolchain guide](toolchain).
+
+---
+
+1. Clone your fork and `cd` into the project:
+
+  ```sh
+  git clone https://github.com/<your-github-username>/tamr-client
+  cd tamr-client
+  ```
+
+2. Set a Python version for this project. Must be Python 3.6+ (e.g. `3.7.3`):
+
+  ```sh
+  pyenv local 3.7.3
+  ```
+
+3. Check that your Python version matches the version specified in `.python-version`:
+
+  ```sh
+  cat .python-version
+  python --version
+  ```
+
+4. Install dependencies via `poetry`:
+
+  ```sh
+  poetry install
+  ```

docs/contributor-guide/migration.md

@@ -0,0 +1,5 @@
+# Code Migrations
+
+Some of the codebase is old and outdated.
+
+To know which patterns to follow and which to avoid, you can check out [ongoing code migrations](https://github.com/Datatamer/tamr-client/labels/%F0%9F%93%88%20Ongoing%20Migration)

docs/contributor-guide/navigating-inheritance.md

@@ -0,0 +1,25 @@
+# Navigating Inheritance
+
+Older parts of the codebase heavily use inheritance.
+We are in the process of [migrating to `dataclasses`](https://github.com/Datatamer/tamr-client/issues/309) to simplify the codebase, but in the meantime you might want to know how the inheritance machinery we have works.
+
+---
+
+`yourResource` and `yourCollection` are files that inherit from `baseResource` and `baseCollection`. Examples of such files would be `resource.py` and `collection.py` in the `attribute_configuration` folder under `project`.
+
+![collection route](resource:collectionRoute.png)
+![collection request](resource:collectionRequest.png)
+
+**Step 1 (red)**: `yourCollection`’s `by_relative_id` returns `super.by_relative_id`, which comes from `baseCollection`
+
+**Step 1a (black)**: within `by_relative_id`, variable `resource_json` is defined as `self.client.get.[etc]`. `Client`’s `.get` returns `self.request`
+
+**Step 1b (black)**: `client`’s `.request` makes a request to the provided URL (this is the method actually fetching the data)
+
+**Step 2 (orange)**: `baseCollection`’s `by_relative_id` returns `resource_class.from_json`, which is the `from_json` defined in `yourResource`
+
+**Step 3 (yellow)**: `yourResource`’s `from_json` returns `super.from_data`, which comes from `baseResource`
+
+**Step 4 (green)**: `baseResource`’s `from_data` returns `cls` , one of the parameters entered for `from_data`.
+`cls` is a `yourResource`, because in `from_json` the return type is specified to be a `yourResource`.
+When `cls` is returned, a `yourResource` that has been filled with the data retrieved in `client`’s `.request` is what comes back.

docs/contributor-guide/pull-request.md

@@ -0,0 +1,44 @@
+# ↪️ Pull Requests
+
+For larger, new features:
+
+  [Open an RFC issue](https://github.com/Datatamer/tamr-client/issues/new/choose).
+  Discuss the feature with project maintainers to be sure that your change fits with the project vision and that you won't be wasting effort going in the wrong direction.
+
+  Once you get the green light 🚦 from maintainers, you can proceed with the PR.
+
+---
+
+Contributions / PRs should follow the
+[Forking Workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/forking-workflow):
+
+  1. Fork it: `https://github.com/[your-github-username]/tamr-client/fork`
+  2. Create your feature branch:
+
+      ```sh
+      git checkout -b my-new-feature
+      ```
+
+  3. Commit your changes:
+
+      ```sh
+      git commit -am 'Add some feature'
+      ```
+
+  4. Push to the branch:
+
+      ```sh
+      git push origin my-new-feature
+      ```
+
+  5. Create a new Pull Request
+
+----
+
+We optimize for PR readability, so please squash commits before and during the PR review process if you think it will help reviewers and onlookers navigate your changes.
+
+Don't be afraid to `push -f` on your PRs when it helps our eyes read your code.
+
+---
+
+Remember to check for any [ongoing code migrations](migration) that may be relevant to your PR.

docs/contributor-guide/run-and-build.md

@@ -0,0 +1,63 @@
+# Run and Build
+
+This project uses [invoke](http://www.pyinvoke.org/) as its task runner.
+
+Since `invoke` will be running inside of a `poetry` environment, we recommend adding the following alias to your `.bashrc` / `.zshrc` to save you some keystrokes:
+
+```sh
+alias pri='poetry run invoke'
+```
+
+## Tests
+
+To run all tests:
+
+```sh  
+pri test # with alias
+poetry run invoke test # without alias
+```
+
+To run specific tests, see [these pytest docs](https://docs.pytest.org/en/latest/usage.html#specifying-tests-selecting-tests) and run `pytest` explicitly:
+
+```sh
+poetry run pytest tests/unit/test_attribute.py
+```
+
+## Linting & Formatting
+
+To run linter:
+
+```sh
+pri lint # with alias
+poetry run invoke lint # without alias
+```
+
+To run formatter:
+
+```sh
+pri format # with alias
+poetry run invoke format # without alias
+```
+
+Run the formatter with the `--fix` flag to autofix formatting:
+
+```sh
+pri format --fix # with alias
+poetry run invoke format --fix # without alias
+```
+
+## Docs
+
+To build the docs:
+
+```sh
+pri docs # with alias
+poetry run invoke docs # without alias
+```
+
+After docs are build, view them by:
+
+```sh
+    open -a 'firefox' docs/_build/index.html # open in Firefox
+    open -a 'Google Chrome' docs/_build/index.html # open in Chrome
+```