Merge pull request #2 from monkut/fix/update-readme

Fix/update readme

Author: monkut

README.md

@@ -2,33 +2,34 @@
 
 This project is intended to provide tools to make it easier to discover the current state of multiple GITHUB Organizational projects.
 
-## Usage
 
-The main interface is through the `ghorgs.managers.GithubOrganizationManager` class.
-This class allows you to obtain all the projects assigned to a given organization, with the option to filter projects based on the project name.
+## GithubOrganizationManager class
 
-> NOTE: Github token may be set in the GITHUB_ACCESS_TOKEN environment variable.
+The main user interface is through the `ghorgs.managers.GithubOrganizationManager` class.
 
-Example:
-```
-from ghorgs.managers import GithubOrganizationManager
-ORGANIZATION = 'my orgnaization'
-PROJECT_NAMES_FILTER = ['My Org Project Name']
-manager = GithubOrganizationManager(github_oauth_token,
-                                    ORGANIZATION)
-for project in manager.projects():
-    for issue in project.issues():
-        print(issue.simple)
-```
+### GithubOrganizationManager Methods
+
+- `create_organizational_project(name: str, description: str, columns: list =None) -> Tuple[str, List[object]]`
+    - Creates a new *organizational project*
+
+- `projects() -> Generator[GithubOrganizationProject, None, None]`
+    - returns a generator yielding `GithubOrganizationProject()` objects
+
+- `repositories(names: List[str]=None) -> Generator[GithubRepository, None, None]`
+    - returns a generator yielding `GithubRepository` objects
+
+
+## GithubOrganizationProject class
+
+### GithubOrganizationProject methods
 
 The `GithubOrganizationManager.projects()` method *yields* `GithubOrganizationProject` objects.
 `GithubOrganizationProject` objects wrap the github API returned JSON by providing the following convience methods:
 
-*issues*
-
-- Method that provides all issues attached to an *organzation project*, with the option to filter by *column_name*
-    Returns a list of github issues containing the following information:
-- Resulting in a GithubIssue object that wraps the JSON object returned by the github API.
+- `issues()`
+    - Method that provides all issues attached to an *organzation project*, with the option to filter by *column_name*
+        Returns a list of github issues containing the following information:
+    - Resulting in a GithubIssue object that wraps the JSON object returned by the github API.
 
 ```
 # Returned issue information:
@@ -54,9 +55,9 @@ ISSUE_DESCRIPTION, (str)
 ]
 ```
 
-*columns*
+- `columns()`
+    - Returns all available column data assigned to the project.
 
-- Returns all available column data assigned to the project.
 ```
 [
     {
@@ -68,6 +69,23 @@ ISSUE_DESCRIPTION, (str)
         'updated_at': '2017-03-27T04:11:18Z',
         'url': 'https://api.github.com/projects/columns/11111'
      },
-    ...     
+    ...
  ]
 ```
+
+
+## Usage
+
+> NOTE: Github token may be set in the GITHUB_ACCESS_TOKEN environment variable.
+
+Example:
+```
+from ghorgs.managers import GithubOrganizationManager
+ORGANIZATION = 'my orgnaization'
+manager = GithubOrganizationManager(github_oauth_token,
+                                    ORGANIZATION)
+for project in manager.projects():
+    for issue in project.issues():
+        print(issue.simple)
+```
+

ghorgs/__init__.py

@@ -1 +1 @@
-__version__ = '0.2.0'
+__version__ = '0.2.1'

ghorgs/exceptions.py

@@ -3,4 +3,4 @@ class GithubGraphQLError(Exception):
 
 
 class UnexpectedResponseError(Exception):
-    pass
+    pass

ghorgs/managers.py

@@ -6,7 +6,7 @@
 import json
 import uuid
 import logging
-from typing import Tuple, List
+from typing import Tuple, List, Generator
 from functools import lru_cache
 
 import requests
@@ -33,7 +33,7 @@ def __init__(self, github_organization_name: str, token: str):
         self.organization = github_organization_name
         self.token = token
 
-    def _get_owner_id(self, name):
+    def _get_owner_id(self, name: str) -> str:
         """Performs a lookup for the related internal github ID needed as a key for other queries"""
         query = """
         {
@@ -131,7 +131,7 @@ def create_organizational_project(self, name: str, description: str, columns: li
 
         return project_url, responses
 
-    def add_columns(self, project_id, columns):
+    def add_columns(self, project_id: str, columns: List[dict]) -> List:
         """
         Add column(s) to the given project.
 
@@ -173,7 +173,7 @@ class GithubOrganizationManager(GithubPagedRequestHandler):
     Functions/Tools for managing Github Organization Projects
     """
 
-    def __init__(self, oauth_token=GITHUB_ACCESS_TOKEN, org=None):
+    def __init__(self, oauth_token: str=GITHUB_ACCESS_TOKEN, org: str=None):
         """
         :param oauth_token: GITHUB OAUTH TOKEN
         :param org: GITHUB ORGANIZATION NAME
@@ -220,7 +220,7 @@ def create_organizational_project(self, *args, **kwargs) -> Tuple[str, List[obje
         return graphql_manager.create_organizational_project(*args, **kwargs)
 
     @lru_cache(maxsize=10)
-    def projects(self):
+    def projects(self) -> Generator[GithubOrganizationProject, None, None]:
         """
         :return: list of organization project objects
         """
@@ -232,15 +232,15 @@ def projects(self):
         yield from (GithubOrganizationProject(self._session, p) for p in projects_data)
 
     @lru_cache(maxsize=10)
-    def repositories(self, names=None):
-        def classify(repository_dict):
+    def repositories(self, names: List[str]=None) -> Generator[GithubRepository, None, None]:
+        def classify(repository_response: dict) -> GithubRepository:
             """
-            Load Github repository API dictionary representation to an internally defined GitRepository Object
-            :param repository_dict: (dict) github Repository dictionary Representation
+            Load Github repository API dictionary representation into an internally defined GitRepository Object
+            :param repository_response: (dict) github Repository dictionary Representation
             :return: (obj) GithubRepository
             """
-            repoository_json = json.dumps(repository_dict)
-            repository = json.loads(repoository_json, object_hook=GithubRepository.from_dict)
+            repository_json = json.dumps(repository_response)
+            repository = json.loads(repository_json, object_hook=GithubRepository.from_dict)
             repository._session = self._session  # attach session so queries can be made
             repository._org = self.org
             return repository
@@ -298,6 +298,3 @@ def classify(repository_dict):
             print('---')
             for urls in project.repository_urls():
                 print(urls)
-
-
-