From 8f184d93affd1e925995cf4e3d27be931cc81318 Mon Sep 17 00:00:00 2001 From: Vincent Jacques Date: Fri, 7 Sep 2012 23:48:43 +0200 Subject: [PATCH] Reconciliate generated code with shipped code (no impact on shipped code, only re-ordering) --- .../description.human_readable.json | 57 ++++-- .../description.normalized.json | 184 ++++++++++++++---- codegen/generate.py | 4 +- codegen/templates/GithubObject.py | 5 - codegen/templates/ReferenceOfClasses.Type.md | 2 +- codegen/templates/ReferenceOfClasses.md | 49 ++++- doc/ReferenceOfApis.md | 8 +- doc/ReferenceOfClasses.md | 8 +- github/Organization.py | 2 +- github/Repository.py | 18 +- 10 files changed, 253 insertions(+), 84 deletions(-) diff --git a/codegen/JsonDescriptionOfGithubApiV3/description.human_readable.json b/codegen/JsonDescriptionOfGithubApiV3/description.human_readable.json index 514b43ef..a5acaec9 100644 --- a/codegen/JsonDescriptionOfGithubApiV3/description.human_readable.json +++ b/codegen/JsonDescriptionOfGithubApiV3/description.human_readable.json @@ -12,7 +12,7 @@ { "name": "AuthenticatedUser", "url": [ - { "type": "constant", "value": "https://api.github.com/user" } + { "type": "constant", "value": "/user" } ], "edit": { "optionalParameters": [ @@ -58,7 +58,7 @@ "singularName": "authorization", "type": "Authorization", "url": [ - { "type": "constant", "value": "https://api.github.com/authorizations" } + { "type": "constant", "value": "/authorizations" } ], "createElement": { "optionalParameters": [ @@ -77,20 +77,20 @@ "singularName": "event", "type": "Event", "getList": true, - "url": [ { "type": "constant", "value": "https://api.github.com/events" } ] + "url": [ { "type": "constant", "value": "/events" } ] }, { "name": "issues", "singularName": "issue", "type": "Issue", "getList": true, - "url": [ { "type": "constant", "value": "https://api.github.com/issues" } ] + "url": [ { "type": "constant", "value": "/issues" } ] }, { "name": "keys", "singularName": "key", "type": "UserKey", - "url": [ { "type": "constant", "value": "https://api.github.com/user/keys" } ], + "url": [ { "type": "constant", "value": "/user/keys" } ], "getList": true, "getElement": { "parameter": { "name": "id", "type": "integer" } @@ -116,7 +116,7 @@ "getElement": { "parameter": { "name": "name", "type": "string" }, "url": [ - { "type": "constant", "value": "https://api.github.com/repos/" }, + { "type": "constant", "value": "/repos/" }, { "type": "attribute", "value": [ "login" ] }, { "type": "constant", "value": "/" }, { "type": "argument", "value": [ "name" ] } @@ -189,7 +189,7 @@ ] }, "url": [ - { "type": "constant", "value": "https://api.github.com/gists" } + { "type": "constant", "value": "/gists" } ] } ], @@ -204,7 +204,7 @@ "request": { "verb": "POST", "url": [ - { "type": "constant", "value": "https://api.github.com/repos/" }, + { "type": "constant", "value": "/repos/" }, { "type": "argument", "value": [ "repo", "owner", "login" ] }, { "type": "constant", "value": "/" }, { "type": "argument", "value": [ "repo", "name" ] }, @@ -223,7 +223,7 @@ "request": { "verb": "GET", "url": [ - { "type": "constant", "value": "https://api.github.com/users/" }, + { "type": "constant", "value": "/users/" }, { "type": "attribute", "value": [ "login" ] }, { "type": "constant", "value": "/events/orgs/" }, { "type": "argument", "value": [ "org", "login" ] } @@ -238,7 +238,7 @@ "request": { "verb": "GET", "url": [ - { "type": "constant", "value": "https://api.github.com/gists/starred" } + { "type": "constant", "value": "/gists/starred" } ], "information": "status" } @@ -455,7 +455,7 @@ "getElement": { "parameter": { "name": "id", "type": "integer" }, "url": [ - { "type": "constant", "value": "https://api.github.com/gists/comments/" }, + { "type": "constant", "value": "/gists/comments/" }, { "type": "stringOf", "value": [ { "type": "argument", "value": [ "id" ] } ] @@ -629,7 +629,7 @@ { "name": "GitAuthor", "attributes": [ - { "name": "date", "type": "string" }, + { "name": "date", "type": "datetime" }, { "name": "email", "type": "string" }, { "name": "name", "type": "string" } ] @@ -930,7 +930,7 @@ "getElement": { "parameter": { "name": "name", "type": "string" }, "url": [ - { "type": "constant", "value": "https://api.github.com/repos/" }, + { "type": "constant", "value": "/repos/" }, { "type": "attribute", "value": [ "login" ] }, { "type": "constant", "value": "/" }, { "type": "argument", "value": [ "name" ] } @@ -1078,7 +1078,7 @@ "getElement": { "parameter": { "name": "name", "type": "string" }, "url": [ - { "type": "constant", "value": "https://api.github.com/repos/" }, + { "type": "constant", "value": "/repos/" }, { "type": "attribute", "value": [ "login" ] }, { "type": "constant", "value": "/" }, { "type": "argument", "value": [ "name" ] } @@ -1116,7 +1116,7 @@ "getElement": { "parameter": { "name": "id", "type": "integer" }, "url" : [ - { "type": "constant", "value": "https://api.github.com/teams/" }, + { "type": "constant", "value": "/teams/" }, { "type": "stringOf", "value": [ { "type": "argument", "value": [ "id" ] } ] @@ -1136,7 +1136,7 @@ "request": { "verb": "POST", "url": [ - { "type": "constant", "value": "https://api.github.com/repos/" }, + { "type": "constant", "value": "/repos/" }, { "type": "argument", "value": [ "repo", "owner", "login" ] }, { "type": "constant", "value": "/" }, { "type": "argument", "value": [ "repo", "name" ] }, @@ -1354,6 +1354,7 @@ { "name": "has_downloads", "type": "bool" } ] }, + "delete": true, "attributes": [ { "name": "clone_url", "type": "string" }, { "name": "created_at", "type": "datetime" }, @@ -1754,7 +1755,7 @@ "request": { "verb": "GET", "url": [ - { "type": "constant", "value": "https://api.github.com/networks/" }, + { "type": "constant", "value": "/networks/" }, { "type": "attribute", "value": [ "owner", "login" ] }, { "type": "constant", "value": "/" }, { "type": "attribute", "value": [ "name" ] }, @@ -1792,6 +1793,28 @@ { "type": "argument", "value": [ "head" ] } ] } + }, + { + "name": [ "legacy", "search", "issues" ], + "type": "list:Issue", + "group": "issues", + "mandatoryParameters": [ + { "name": "state", "type": "string" }, + { "name": "keyword", "type": "string" } + ], + "request": { + "verb": "GET", + "url": [ + { "type": "constant", "value": "/legacy/issues/search/" }, + { "type": "attribute", "value": [ "owner", "login" ] }, + { "type": "constant", "value": "/" }, + { "type": "attribute", "value": [ "name" ] }, + { "type": "constant", "value": "/" }, + { "type": "argument", "value": [ "state" ] }, + { "type": "constant", "value": "/" }, + { "type": "urlquote", "value": [ { "type": "argument", "value": [ "keyword" ] } ] } + ] + } } ] }, diff --git a/codegen/JsonDescriptionOfGithubApiV3/description.normalized.json b/codegen/JsonDescriptionOfGithubApiV3/description.normalized.json index 8a9a222b..14228028 100644 --- a/codegen/JsonDescriptionOfGithubApiV3/description.normalized.json +++ b/codegen/JsonDescriptionOfGithubApiV3/description.normalized.json @@ -216,7 +216,7 @@ "url": [ { "type": "constant", - "value": "https://api.github.com/user" + "value": "/user" } ], "postParameters": true, @@ -299,7 +299,7 @@ "url": [ { "type": "constant", - "value": "https://api.github.com/authorizations" + "value": "/authorizations" } ], "information": "status", @@ -359,7 +359,7 @@ "url": [ { "type": "constant", - "value": "https://api.github.com/authorizations/" + "value": "/authorizations/" }, { "type": "stringOf", @@ -395,7 +395,7 @@ "url": [ { "type": "constant", - "value": "https://api.github.com/authorizations" + "value": "/authorizations" } ], "information": "data", @@ -420,7 +420,7 @@ "url": [ { "type": "constant", - "value": "https://api.github.com/events" + "value": "/events" } ], "information": "data", @@ -445,7 +445,7 @@ "url": [ { "type": "constant", - "value": "https://api.github.com/issues" + "value": "/issues" } ], "information": "data", @@ -487,7 +487,7 @@ "url": [ { "type": "constant", - "value": "https://api.github.com/user/keys" + "value": "/user/keys" } ], "information": "status", @@ -522,7 +522,7 @@ "url": [ { "type": "constant", - "value": "https://api.github.com/user/keys/" + "value": "/user/keys/" }, { "type": "stringOf", @@ -558,7 +558,7 @@ "url": [ { "type": "constant", - "value": "https://api.github.com/user/keys" + "value": "/user/keys" } ], "information": "data", @@ -592,7 +592,7 @@ "url": [ { "type": "constant", - "value": "https://api.github.com/user/repos" + "value": "/user/repos" } ], "information": "status", @@ -676,7 +676,7 @@ "url": [ { "type": "constant", - "value": "https://api.github.com/repos/" + "value": "/repos/" }, { "type": "attribute", @@ -717,7 +717,7 @@ "url": [ { "type": "constant", - "value": "https://api.github.com/user/repos" + "value": "/user/repos" } ], "information": "data", @@ -776,7 +776,7 @@ "url": [ { "type": "constant", - "value": "https://api.github.com/user/emails" + "value": "/user/emails" } ], "information": "status", @@ -802,7 +802,7 @@ "url": [ { "type": "constant", - "value": "https://api.github.com/user/emails" + "value": "/user/emails" } ], "information": "data", @@ -836,7 +836,7 @@ "url": [ { "type": "constant", - "value": "https://api.github.com/user/emails" + "value": "/user/emails" } ], "information": "status", @@ -872,7 +872,7 @@ "url": [ { "type": "constant", - "value": "https://api.github.com/user/watched/" + "value": "/user/watched/" }, { "type": "identity", @@ -903,7 +903,7 @@ "url": [ { "type": "constant", - "value": "https://api.github.com/user/watched" + "value": "/user/watched" } ], "information": "data", @@ -938,7 +938,7 @@ "url": [ { "type": "constant", - "value": "https://api.github.com/user/watched/" + "value": "/user/watched/" }, { "type": "identity", @@ -979,7 +979,7 @@ "url": [ { "type": "constant", - "value": "https://api.github.com/user/watched/" + "value": "/user/watched/" }, { "type": "identity", @@ -1020,7 +1020,7 @@ "url": [ { "type": "constant", - "value": "https://api.github.com/user/following/" + "value": "/user/following/" }, { "type": "identity", @@ -1051,7 +1051,7 @@ "url": [ { "type": "constant", - "value": "https://api.github.com/user/following" + "value": "/user/following" } ], "information": "data", @@ -1086,7 +1086,7 @@ "url": [ { "type": "constant", - "value": "https://api.github.com/user/following/" + "value": "/user/following/" }, { "type": "identity", @@ -1127,7 +1127,7 @@ "url": [ { "type": "constant", - "value": "https://api.github.com/user/following/" + "value": "/user/following/" }, { "type": "identity", @@ -1158,7 +1158,7 @@ "url": [ { "type": "constant", - "value": "https://api.github.com/user/followers" + "value": "/user/followers" } ], "information": "data", @@ -1183,7 +1183,7 @@ "url": [ { "type": "constant", - "value": "https://api.github.com/user/orgs" + "value": "/user/orgs" } ], "information": "data", @@ -1226,7 +1226,7 @@ "url": [ { "type": "constant", - "value": "https://api.github.com/gists" + "value": "/gists" } ], "information": "status", @@ -1261,7 +1261,7 @@ "url": [ { "type": "constant", - "value": "https://api.github.com/gists" + "value": "/gists" } ], "information": "data", @@ -1295,7 +1295,7 @@ "url": [ { "type": "constant", - "value": "https://api.github.com/repos/" + "value": "/repos/" }, { "type": "argument", @@ -1353,7 +1353,7 @@ "url": [ { "type": "constant", - "value": "https://api.github.com/users/" + "value": "/users/" }, { "type": "attribute", @@ -1396,7 +1396,7 @@ "url": [ { "type": "constant", - "value": "https://api.github.com/gists/starred" + "value": "/gists/starred" } ], "information": "status", @@ -2704,7 +2704,7 @@ "url": [ { "type": "constant", - "value": "https://api.github.com/gists/comments/" + "value": "/gists/comments/" }, { "type": "stringOf", @@ -3104,7 +3104,7 @@ "type": { "simple": true, "cardinality": "scalar", - "name": "string" + "name": "datetime" }, "name": "date" }, @@ -5243,7 +5243,7 @@ "url": [ { "type": "constant", - "value": "https://api.github.com/repos/" + "value": "/repos/" }, { "type": "attribute", @@ -6281,7 +6281,7 @@ "url": [ { "type": "constant", - "value": "https://api.github.com/repos/" + "value": "/repos/" }, { "type": "attribute", @@ -6429,7 +6429,7 @@ "url": [ { "type": "constant", - "value": "https://api.github.com/teams/" + "value": "/teams/" }, { "type": "stringOf", @@ -6505,7 +6505,7 @@ "url": [ { "type": "constant", - "value": "https://api.github.com/repos/" + "value": "/repos/" }, { "type": "argument", @@ -7766,6 +7766,32 @@ "name": "void" } }, + { + "group": "deletion", + "name": [ + "delete" + ], + "mandatoryParameters": [], + "request": { + "url": [ + { + "type": "attribute", + "value": [ + "url" + ] + } + ], + "information": "data", + "verb": "DELETE" + }, + "isMutation": false, + "optionalParameters": [], + "type": { + "simple": true, + "cardinality": "scalar", + "name": "void" + } + }, { "group": "branches", "name": [ @@ -10107,7 +10133,7 @@ "url": [ { "type": "constant", - "value": "https://api.github.com/networks/" + "value": "/networks/" }, { "type": "attribute", @@ -10233,6 +10259,90 @@ "cardinality": "scalar", "name": "Comparison" } + }, + { + "group": "issues", + "name": [ + "legacy", + "search", + "issues" + ], + "mandatoryParameters": [ + { + "type": { + "simple": true, + "cardinality": "scalar", + "name": "string" + }, + "name": "state" + }, + { + "type": { + "simple": true, + "cardinality": "scalar", + "name": "string" + }, + "name": "keyword" + } + ], + "request": { + "url": [ + { + "type": "constant", + "value": "/legacy/issues/search/" + }, + { + "type": "attribute", + "value": [ + "owner", + "login" + ] + }, + { + "type": "constant", + "value": "/" + }, + { + "type": "attribute", + "value": [ + "name" + ] + }, + { + "type": "constant", + "value": "/" + }, + { + "type": "argument", + "value": [ + "state" + ] + }, + { + "type": "constant", + "value": "/" + }, + { + "type": "urlquote", + "value": [ + { + "type": "argument", + "value": [ + "keyword" + ] + } + ] + } + ], + "verb": "GET" + }, + "isMutation": false, + "optionalParameters": [], + "type": { + "simple": false, + "cardinality": "list", + "name": "Issue" + } } ] }, diff --git a/codegen/generate.py b/codegen/generate.py index 830e7319..df7566e7 100755 --- a/codegen/generate.py +++ b/codegen/generate.py @@ -37,6 +37,8 @@ for class_ in description[ "classes" ]: for method in class_[ "methods" ]: if method[ "type" ][ "cardinality" ] == "list": + if not method[ "type" ][ "simple" ]: + method[ "type" ][ "cardinality" ] = "iterator" class_[ "needsPaginatedList" ] = True if len( method[ "optionalParameters" ] ) != 0: class_[ "needsDefaultValue" ] = True @@ -49,8 +51,6 @@ for class_ in description[ "classes" ]: for attribute in class_[ "attributes" ]: if not attribute[ "type" ][ "simple" ]: dependencies.add( attribute[ "type" ][ "name" ] ) - if attribute[ "type" ][ "name" ] == "datetime": - class_[ "needsDatetime" ] = True class_[ "dependencies" ] = list( dependencies ) class_[ "needsUrllib" ] = class_[ "name" ] in [ "Label", "Repository" ] diff --git a/codegen/templates/GithubObject.py b/codegen/templates/GithubObject.py index 89014185..ecd7698c 100644 --- a/codegen/templates/GithubObject.py +++ b/codegen/templates/GithubObject.py @@ -14,11 +14,6 @@ {% if class.needsUrllib %} import urllib -{% endif %} -{% if class.needsDatetime %} -import datetime -{% endif %} -{% if class.needsUrllib or class.needsDatetime %} ########## {% endif %} diff --git a/codegen/templates/ReferenceOfClasses.Type.md b/codegen/templates/ReferenceOfClasses.Type.md index cdb0734b..3e971f18 100644 --- a/codegen/templates/ReferenceOfClasses.Type.md +++ b/codegen/templates/ReferenceOfClasses.Type.md @@ -1 +1 @@ -{% if type.name != "void" %}: {% if type.cardinality == "list" %}list of {% endif %}{% if type.cardinality == "dict" %}dict of {{ type.key_name }} to {% endif %}{% if not type.simple %}`{% endif %}{{ type.name }}{% if not type.simple %}`{% endif %}{% endif %} \ No newline at end of file +{% if type.name != "void" %}: {% if type.cardinality == "iterator" %}iterator of {% endif %}{% if type.cardinality == "list" %}list of {% endif %}{% if type.cardinality == "dict" %}dict of {{ type.key_name }} to {% endif %}{% if not type.simple %}`{% endif %}{% if type.name == "datetime" %}datetime.datetime{% else %}{{ type.name }}{% endif %}{% if not type.simple %}`{% endif %}{% endif %} \ No newline at end of file diff --git a/codegen/templates/ReferenceOfClasses.md b/codegen/templates/ReferenceOfClasses.md index fb6550ef..af2d1b2e 100644 --- a/codegen/templates/ReferenceOfClasses.md +++ b/codegen/templates/ReferenceOfClasses.md @@ -1,15 +1,56 @@ You don't normaly create instances of any class but `Github`. -You obtain instances through calls to `get_` and `create_` methods. +You obtain instances through calls to `search_`, `get_` and `create_` methods. + +Methods returning an "iterator of `SomeType`" return an iterator which yields instances of `SomeType`. +This implements lazy [pagination requests](http://developer.github.com/v3/#pagination). +You can use this iterator in a `for f in user.get_followers():` loop or with any [itertools](http://docs.python.org/library/itertools.html) functions, +but you cannot know the number of objects returned before the end of the iteration. +If that's really what you need, you cant use `len( list( user.get_followers() ) )`, which does all the requests needed to enumerate the user's followers. +Note that there is often an attribute giving this value (in that case `user.followers`). Class `Github` ============== -* Constructed from user's login and password or OAuth token + +Constructed from user's login and password or OAuth token or nothing: + + g = Github( login, password ) + g = Github( token ) + g = Github() + +You can add an argument `base_url = "http://my.enterprise.com:8080/path/to/github"` to connect to a local install of Github (ie. Github Enterprise). +Another argument, that can be passed is `timeout` which has default value `10`. + +Attributes +---------- +* `rate_limiting`: tuple of two integers: remaining and limit, as explained in [Rate Limiting](http://developer.github.com/v3/#rate-limiting) + +Methods +------- * `get_user()`: `AuthenticatedUser` * `get_user( login )`: `NamedUser` * `get_organization( login )`: `Organization` * `get_gist( id )`: `Gist` -* `get_gists()`: list of `Gist` -* `rate_limiting`: tuple of two integers: remaining and limit, as explained in [Rate Limiting](http://developer.github.com/v3/#rate-limiting) + * `id`: string +* `get_gists()`: iterator of `Gist` +* `search_repos( keyword )`: iterator of `Repository` +* `legacy_search_repos( keyword, [language] )`: iterator of `Repository` + * `keyword`: string + * `language`: string +* `legacy_search_users( keyword )`: iterator of `NamedUser` + * `keyword`: string +* `legacy_search_user_by_email( email )`: `NamedUser` + * `email`: string +* `render_markdown( text, [context] )`: string + * `text`: string + * `context`: `Repository` + +Class `GithubException` +======================= + +Attributes +---------- +* `status`: integer +* `data`: dict {% for class in classes|dictsort:"name" %} Class `{{ class.name }}` diff --git a/doc/ReferenceOfApis.md b/doc/ReferenceOfApis.md index 8165510f..f2d14624 100644 --- a/doc/ReferenceOfApis.md +++ b/doc/ReferenceOfApis.md @@ -65,14 +65,14 @@ API `/legacy/repos/search/:keyword` =================================== * GET: `Github.search_repos` -API `/legacy/user/search/:keyword` -================================== -* GET: `Github.search_users` - API `/legacy/user/email/:email` =============================== * GET: `Github.search_user_by_email` +API `/legacy/user/search/:keyword` +================================== +* GET: `Github.search_users` + API `/markdown` =============== * POST: `Github.render_markdown` diff --git a/doc/ReferenceOfClasses.md b/doc/ReferenceOfClasses.md index b82d109e..52099f17 100644 --- a/doc/ReferenceOfClasses.md +++ b/doc/ReferenceOfClasses.md @@ -1077,10 +1077,6 @@ Attributes * `url`: string * `watchers`: integer -Deletion --------- -* `delete()` - Comparison ---------- * `compare( base, head )`: `Comparison` @@ -1119,6 +1115,10 @@ Contributors ------------ * `get_contributors()`: iterator of `NamedUser` +Deletion +-------- +* `delete()` + Downloads --------- * `create_download( name, size, [description, content_type] )`: `Download` diff --git a/github/Organization.py b/github/Organization.py index 3f52eb69..8cbfdd4e 100644 --- a/github/Organization.py +++ b/github/Organization.py @@ -17,8 +17,8 @@ import GithubObject import PaginatedList -import Team import Plan +import Team import Event import Repository import NamedUser diff --git a/github/Repository.py b/github/Repository.py index b78fe96d..c08526e4 100644 --- a/github/Repository.py +++ b/github/Repository.py @@ -1002,15 +1002,6 @@ class Repository( GithubObject.GithubObject ): ) return status == 204 - def remove_from_collaborators( self, collaborator ): - assert isinstance( collaborator, NamedUser.NamedUser ), collaborator - headers, data = self._requester.requestAndCheck( - "DELETE", - self.url + "/collaborators/" + collaborator._identity, - None, - None - ) - def legacy_search_issues( self, state, keyword ): assert state in [ "open", "closed" ], state assert isinstance( keyword, ( str, unicode ) ), keyword @@ -1025,6 +1016,15 @@ class Repository( GithubObject.GithubObject ): for element in data[ "issues" ] ] + def remove_from_collaborators( self, collaborator ): + assert isinstance( collaborator, NamedUser.NamedUser ), collaborator + headers, data = self._requester.requestAndCheck( + "DELETE", + self.url + "/collaborators/" + collaborator._identity, + None, + None + ) + @property def _identity( self ): return self.owner.login + "/" + self.name