diff --git a/generateDocstrings.py b/generateDocstrings.py old mode 100644 new mode 100755 index 338b3733..ddc6b35e --- a/generateDocstrings.py +++ b/generateDocstrings.py @@ -1,161 +1,165 @@ -#!/usr/bin/env python - -import subprocess -import glob -import re -import collections - -class ClassDescription: - def __init__( self ): - self.properties = dict() - self.methods = collections.OrderedDict() - -class MethodDescription: - def __init__( self, returnType ): - self.verb = None - self.url = None - self.returnType = returnType - self.parameters = collections.OrderedDict() - -class Generator(): - privateClasses = [ - "PaginatedList", - "PaginatedListBase", - "GithubObject", - "BasicGithubObject", - "_NotSetType", - "Requester", - ] - - def getClassDocstring( self, className ): - if className in self.privateClasses: - return [] - else: - return [ - "Please edit this generated docstring for class " + className + ".", - ] - - def getMemberDocstring( self, className, memberName ): - if className in self.privateClasses: - return [] - elif className in self.classDescriptions: - classDescription = self.classDescriptions[ className ] - if memberName in classDescription.properties: - return [ - "Please edit this generated docstring for property " + className + "." + memberName + ".", - "", - ":type: " + classDescription.properties[ memberName ] - ] - elif memberName in classDescription.methods: - return [ - "Please edit this generated docstring for method " + className + "." + memberName + ".", - "", - "Calls " + ( classDescription.methods[ memberName ].verb or "WTF" ) + " " + ( classDescription.methods[ memberName ].url or "WTF" ), - "", - ] + [ - ":param " + parameterName + ": " + parameterType for parameterName, parameterType in classDescription.methods[ memberName ].parameters.items() - ] + [ - ":return: " + str( classDescription.methods[ memberName ].returnType ) - ] - elif memberName.startswith( "_" ): # private member - return [] - else: - print "Unknown member", className, memberName - return [] - else: - print "Unknown class", className - return [] - - def __init__( self ): - pass - - def run( self ): - self.restoreSources() - self.readReferenceOfClasses() - self.readReferenceOfApis() - self.generate() - - def restoreSources( self ): - subprocess.check_call( [ "git", "checkout", "--", "github" ] ) - - def readReferenceOfClasses( self ): - self.classDescriptions = dict() - with open( "doc/ReferenceOfClasses.md" ) as f: - for line in f: - line = line.rstrip() - if line.startswith( "Class `" ): - className = line[ 7 : -1 ] - self.classDescriptions[ className ] = ClassDescription() - if line.startswith( "*" ): - if "rate_limiting" in line: - self.classDescriptions[ className ].properties[ "rate_limiting" ] = "( int, int )" - elif "(" in line: - methodName, returnType = re.match( "^\* `(.*)\(.*\)`(?:: (.*))?$", line ).groups() - self.classDescriptions[ className ].methods[ methodName ] = MethodDescription( returnType ) - else: - attributeName, attributeType = re.match( "^\* `(.*)`: (.*)$", line ).groups() - self.classDescriptions[ className ].properties[ attributeName ] = attributeType - if line.startswith( " *" ): - parameterName, parameterType = re.match( "^ \* `(.*)`: (.*)$", line ).groups() - self.classDescriptions[ className ].methods[ methodName ].parameters[ parameterName ] = parameterType - - def readReferenceOfApis( self ): - with open( "doc/ReferenceOfApis.md" ) as f: - for line in f: - line = line.rstrip() - if line.startswith( "API" ): - url = line[ 5 : -1 ] - if line.startswith( "*" ) and line not in [ "* POST: see API `/markdown`", "* GET: Not implemented, see `Github.rate_limiting`" ]: - verb, methods = re.match( "^\* (.*): (.*)$", line ).groups() - for method in methods.split( " or " ): - className, methodName = re.match( "^`(.*)\.(.*)`", method ).groups() - self.classDescriptions[ className ].methods[ methodName ].verb = verb - self.classDescriptions[ className ].methods[ methodName ].url = url - - def generate( self ): - for f in glob.glob( "github/*.py" ): - self.generateForFile( f ) - - def generateForFile( self, fileName ): - self.writeLines( fileName, self.processLines( self.readLines( fileName ) ) ) - - def processLines( self, lines ): - nextDefIsStaticMethod = False - nextDefIsClassMethod = False - - for line in lines: - yield line - if line.startswith( "class" ): - className = re.match( "^class (.*?)(?:\(.*\))?:$", line ).group( 1 ) - for docStringLine in self.formatDocstring( " ", self.getClassDocstring( className ) ): - yield docStringLine - if line.startswith( " def" ): - if nextDefIsStaticMethod or nextDefIsClassMethod: - pass - else: - memberName = re.match( "^ def (.*?)\( self.* \):$", line ).group( 1 ) - for docStringLine in self.formatDocstring( " ", self.getMemberDocstring( className, memberName ) ): - yield docStringLine - - nextDefIsStaticMethod = line == " @staticmethod" - nextDefIsClassMethod = line == " @classmethod" - - def formatDocstring( self, indent, lines ): - if len( lines ) != 0: - yield indent + '"""' - for docStringLine in lines: - yield indent + docStringLine - yield indent + '"""' - yield "" - - def readLines( self, fileName ): - with open( fileName ) as f: - return list( line.rstrip() for line in f ) - - def writeLines( self, fileName, lines ): - with open( fileName, "wb" ) as f: - for line in lines: - f.write( line + "\n" ) - -if __name__ == "__main__": - Generator().run() +#!/usr/bin/env python + +import subprocess +import glob +import re +import collections + + +class ClassDescription: + def __init__(self): + self.properties = dict() + self.methods = collections.OrderedDict() + + +class MethodDescription: + def __init__(self, returnType): + self.verb = None + self.url = None + self.returnType = returnType + self.parameters = collections.OrderedDict() + + +class Generator(): + privateClasses = [ + "PaginatedList", + "PaginatedListBase", + "GithubObject", + "BasicGithubObject", + "_NotSetType", + "Requester", + ] + + def getClassDocstring(self, className): + if className in self.privateClasses: + return [] + else: + return [ + "Please edit this generated docstring for class " + className + ".", + ] + + def getMemberDocstring(self, className, memberName): + if className in self.privateClasses: + return [] + elif className in self.classDescriptions: + classDescription = self.classDescriptions[className] + if memberName in classDescription.properties: + return [ + "Please edit this generated docstring for property " + className + "." + memberName + ".", + "", + ":type: " + classDescription.properties[memberName] + ] + elif memberName in classDescription.methods: + return [ + "Please edit this generated docstring for method " + className + "." + memberName + ".", + "", + "Calls " + (classDescription.methods[memberName].verb or "WTF") + " " + (classDescription.methods[memberName].url or "WTF"), + "", + ] + [ + ":param " + parameterName + ": " + parameterType for parameterName, parameterType in classDescription.methods[memberName].parameters.items() + ] + [ + ":return: " + str(classDescription.methods[memberName].returnType) + ] + elif memberName.startswith("_"): # private member + return [] + else: + print "Unknown member", className, memberName + return [] + else: + print "Unknown class", className + return [] + + def __init__(self): + pass + + def run(self): + self.restoreSources() + self.readReferenceOfClasses() + self.readReferenceOfApis() + self.generate() + + def restoreSources(self): + subprocess.check_call(["git", "checkout", "--", "github"]) + + def readReferenceOfClasses(self): + self.classDescriptions = dict() + with open("doc/ReferenceOfClasses.md") as f: + for line in f: + line = line.rstrip() + if line.startswith("Class `"): + className = line[7:-1] + self.classDescriptions[className] = ClassDescription() + if line.startswith("*"): + if "rate_limiting" in line: + self.classDescriptions[className].properties["rate_limiting"] = "(int, int)" + elif "(" in line: + methodName, returnType = re.match("^\* `(.*)\(.*\)`(?:: (.*))?$", line).groups() + self.classDescriptions[className].methods[methodName] = MethodDescription(returnType) + else: + attributeName, attributeType = re.match("^\* `(.*)`: (.*)$", line).groups() + self.classDescriptions[className].properties[attributeName] = attributeType + if line.startswith(" *"): + parameterName, parameterType = re.match("^ \* `(.*)`: (.*)$", line).groups() + self.classDescriptions[className].methods[methodName].parameters[parameterName] = parameterType + + def readReferenceOfApis(self): + with open("doc/ReferenceOfApis.md") as f: + for line in f: + line = line.rstrip() + if line.startswith("API"): + url = line[5:-1] + if line.startswith("*") and line not in ["* POST: see API `/markdown`", "* GET: Not implemented, see `Github.rate_limiting`"]: + verb, methods = re.match("^\* (.*): (.*)$", line).groups() + for method in methods.split(" or "): + className, methodName = re.match("^`(.*)\.(.*)`", method).groups() + self.classDescriptions[className].methods[methodName].verb = verb + self.classDescriptions[className].methods[methodName].url = url + + def generate(self): + for f in glob.glob("github/*.py"): + self.generateForFile(f) + + def generateForFile(self, fileName): + self.writeLines(fileName, self.processLines(self.readLines(fileName))) + + def processLines(self, lines): + nextDefIsStaticMethod = False + nextDefIsClassMethod = False + + for line in lines: + yield line + if line.startswith("class"): + className = re.match("^class (.*?)(?:\(.*\))?:$", line).group(1) + for docStringLine in self.formatDocstring(" ", self.getClassDocstring(className)): + yield docStringLine + if line.startswith(" def"): + if nextDefIsStaticMethod or nextDefIsClassMethod: + pass + else: + assert re.match("^ def (.*?)\(self.*\):$", line), line + memberName = re.match("^ def (.*?)\(self.*\):$", line).group(1) + for docStringLine in self.formatDocstring(" ", self.getMemberDocstring(className, memberName)): + yield docStringLine + + nextDefIsStaticMethod = line == " @staticmethod" + nextDefIsClassMethod = line == " @classmethod" + + def formatDocstring(self, indent, lines): + if len(lines) != 0: + yield indent + '"""' + for docStringLine in lines: + yield indent + docStringLine + yield indent + '"""' + yield "" + + def readLines(self, fileName): + with open(fileName) as f: + return list(line.rstrip() for line in f) + + def writeLines(self, fileName, lines): + with open(fileName, "wb") as f: + for line in lines: + f.write(line + "\n") + +if __name__ == "__main__": + Generator().run() diff --git a/github/AuthorizationApplication.py b/github/AuthorizationApplication.py index 15326561..c39a6158 100644 --- a/github/AuthorizationApplication.py +++ b/github/AuthorizationApplication.py @@ -17,13 +17,29 @@ import github.GithubObject class AuthorizationApplication(github.GithubObject.GithubObject): + """ + Please edit this generated docstring for class AuthorizationApplication. + """ + @property def name(self): + """ + Please edit this generated docstring for property AuthorizationApplication.name. + + :type: string + """ + self._completeIfNotSet(self._name) return self._NoneIfNotSet(self._name) @property def url(self): + """ + Please edit this generated docstring for property AuthorizationApplication.url. + + :type: string + """ + self._completeIfNotSet(self._url) return self._NoneIfNotSet(self._url) diff --git a/github/Github.py b/github/Github.py index e4e548f6..db7ddd4f 100644 --- a/github/Github.py +++ b/github/Github.py @@ -35,13 +35,13 @@ class Github(object): def __init__(self, login_or_token=None, password=None, base_url=DEFAULT_BASE_URL, timeout=DEFAULT_TIMEOUT, client_id=None, client_secret=None, user_agent=None): self.__requester = Requester(login_or_token, password, base_url, timeout, client_id, client_secret, user_agent) - def get_FIX_REPO_GET_GIT_REF(self): + def __get_FIX_REPO_GET_GIT_REF(self): return self.__requester.FIX_REPO_GET_GIT_REF - def set_FIX_REPO_GET_GIT_REF(self, value): + def __set_FIX_REPO_GET_GIT_REF(self, value): self.__requester.FIX_REPO_GET_GIT_REF = value - FIX_REPO_GET_GIT_REF = property(get_FIX_REPO_GET_GIT_REF, set_FIX_REPO_GET_GIT_REF) + FIX_REPO_GET_GIT_REF = property(__get_FIX_REPO_GET_GIT_REF, __set_FIX_REPO_GET_GIT_REF) @property def rate_limiting(self): diff --git a/github/GithubObject.py b/github/GithubObject.py index dcba0e81..f9f5b949 100644 --- a/github/GithubObject.py +++ b/github/GithubObject.py @@ -19,7 +19,7 @@ import GithubException class _NotSetType: - def __repr__( self ): + def __repr__(self): return "NotSet" NotSet = _NotSetType()