status-im/PyGithub
1
0
Fork 0
mirror of https://github.com/status-im/PyGithub.git synced 2026-09-02 03:41:08 +00:00
Code Issues Packages Projects Releases Wiki Activity

Improve documentation generation

Browse Source
This commit is contained in:
Vincent Jacques
2012-02-26 14:32:29 +00:00
parent f71bf13461
commit 37a62f4c6f
6 changed files with 45 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files
github/GithubObject.UnitTest.py
+3 -3
View File
@@ -409,7 +409,7 @@ class GithubObjectWithMultiCapacityExternalListOfSimpleTypes( TestCaseWithGithub
"GithubTestObject",
BaseUrl( lambda obj: "/test" ),
InternalSimpleAttributes( "a1", "a2" ),
ExternalListOfSimpleTypes( "a3s", "a3",
ExternalListOfSimpleTypes( "a3s", "a3", "",
ListGetable( [], [] ),
SeveralElementsAddable(),
SeveralElementsRemovable(),
@@ -435,10 +435,10 @@ class GithubObjectWithExternalSimpleAttribute( TestCaseWithGithubTestObject ):
"GithubTestObject",
BaseUrl( lambda obj: "/test" ),
InternalSimpleAttributes( "a1", "a2" ),
ExternalSimpleAttribute( "a3" )
ExternalSimpleAttribute( "a3", "" )
)
def testCallMethod( self ):
def testGetAttribute( self ):
self.expectDataGet( "/test/a3" ).andReturn( 72 )
self.assertEqual( self.o.get_a3(), 72 )
github/GithubObject.py
+10 -15
View File
@@ -9,16 +9,16 @@ class BadGithubObjectException( Exception ):
pass
def InternalSimpleAttribute( attributeName ):
return InternalAttribute( attributeName, SimpleTypePolicy() )
return InternalAttribute( attributeName, SimpleTypePolicy( None ) )
def InternalSimpleAttributes( *attributeNames ):
return SeveralAttributePolicies( [ InternalSimpleAttribute( attributeName ) for attributeName in attributeNames ] )
return SeveralAttributePolicies( [ InternalSimpleAttribute( attributeName ) for attributeName in attributeNames ], "Attributes" )
def InternalObjectAttribute( attributeName, type ):
return InternalAttribute( attributeName, ObjectTypePolicy( type ) )
def ExternalSimpleAttribute( attributeName ):
return ExternalAttribute( attributeName, SimpleTypePolicy() )
def ExternalSimpleAttribute( attributeName, type ):
return ExternalAttribute( attributeName, SimpleTypePolicy( type ) )
def BaseUrl( baseUrl ):
return AttributeFromCallable( "_baseUrl", baseUrl )
@@ -26,20 +26,16 @@ def BaseUrl( baseUrl ):
def Identity( identity ):
return AttributeFromCallable( "_identity", identity )
class Editable( MethodFromCallable ):
def __init__( self, mandatoryParameters, optionalParameters ):
MethodFromCallable.__init__( self, "edit", mandatoryParameters, optionalParameters, self.__execute )
def __execute( self, obj, **data ):
def Editable( mandatoryParameters, optionalParameters ):
def __execute( obj, **data ):
attributes = obj._github._dataRequest( "PATCH", obj._baseUrl, None, data )
obj._updateAttributes( attributes )
return SeveralAttributePolicies( [ MethodFromCallable( "edit", mandatoryParameters, optionalParameters, __execute ) ], "Modification" )
class Deletable( MethodFromCallable ):
def __init__( self ):
MethodFromCallable.__init__( self, "delete", [], [], self.__execute )
def __execute( self, obj ):
def Deletable():
def __execute( obj ):
obj._github._statusRequest( "DELETE", obj._baseUrl, None, None )
return SeveralAttributePolicies( [ MethodFromCallable( "delete", [], [], __execute ) ], "Deletion" )
def GithubObject( className, *attributePolicies ):
class GithubObject:
@@ -107,7 +103,6 @@ def GithubObject( className, *attributePolicies ):
def _autoDocument( cls ):
doc = "Class `" + cls.__name__ + "`\n"
doc += "=" * ( len( cls.__name__ ) + 8 ) + "\n"
doc += "* Attributes: see [API]()\n"
for attributePolicy in cls.__attributePolicies:
doc += attributePolicy.autoDocument()
doc += "\n"
github/GithubObjects.py
+2 -2
View File
@@ -15,7 +15,7 @@ AuthenticatedUser = GithubObject(
"disk_usage", "collaborators", "plan",
),
Editable( [], [ "name", "email", "blog", "company", "location", "hireable", "bio" ] ),
ExternalListOfSimpleTypes( "emails", "email",
ExternalListOfSimpleTypes( "emails", "email", "string",
ListGetable( [], [] ),
SeveralElementsAddable(),
SeveralElementsRemovable()
@@ -305,7 +305,7 @@ Repository = GithubObject(
),
InternalObjectAttribute( "owner", NamedUser ),
Editable( [ "name" ], [ "description", "homepage", "public", "has_issues", "has_wiki", "has_downloads" ] ),
ExternalSimpleAttribute( "languages" ),
ExternalSimpleAttribute( "languages", "dictionary from strings to integers" ),
ExternalListOfObjects( "collaborators", "collaborator", NamedUser,
ListGetable( [], [] ),
ElementAddable(),
github/ObjectCapacities/Basic.py
+8 -3
View File
@@ -70,8 +70,13 @@ class InternalAttribute:
cls._addAttribute( self.__attributeName, InternalAttribute.AttributeDefinition( self.__typePolicy ) )
def autoDocument( self ):
return ""
return "* `" + self.__attributeName + "`: `" + self.__typePolicy.documentTypeName() + "`\n"
if self.__attributeName.startswith( "_" ):
return ""
doc = "* `" + self.__attributeName + "`"
if self.__typePolicy.hasMeaningfulDocumentation():
doc += ": " + self.__typePolicy.documentTypeName()
doc += "\n"
return doc
class ExternalAttribute:
def __init__( self, attributeName, typePolicy ):
@@ -88,7 +93,7 @@ class ExternalAttribute:
)
def autoDocument( self ):
return "* `get_" + self.__attributeName + "()`: `" + self.__typePolicy.documentTypeName() + "`\n"
return "* `get_" + self.__attributeName + "()`: " + self.__typePolicy.documentTypeName() + "\n"
class SeveralAttributePolicies:
def __init__( self, attributePolicies, documentationSection = None ):
github/ObjectCapacities/List.py
+11 -11
View File
@@ -25,7 +25,7 @@ class ElementAddable( ListCapacity ):
)
def autoDocument( self ):
return "* `add_to_" + self.safeAttributeName + "( " + self.singularName + " )`\n * `" + self.singularName + "`: `" + self.typePolicy.documentTypeName() + "`\n"
return "* `add_to_" + self.safeAttributeName + "( " + self.singularName + " )`\n * `" + self.singularName + "`: " + self.typePolicy.documentTypeName() + "\n"
class ElementRemovable( ListCapacity ):
def apply( self, cls ):
@@ -40,7 +40,7 @@ class ElementRemovable( ListCapacity ):
)
def autoDocument( self ):
return "* `remove_from_" + self.safeAttributeName + "( " + self.singularName + " )`\n * `" + self.singularName + "`: `" + self.typePolicy.documentTypeName() + "`\n"
return "* `remove_from_" + self.safeAttributeName + "( " + self.singularName + " )`\n * `" + self.singularName + "`: " + self.typePolicy.documentTypeName() + "\n"
class ElementHasable( ListCapacity ):
def apply( self, cls ):
@@ -55,7 +55,7 @@ class ElementHasable( ListCapacity ):
) == 204
def autoDocument( self ):
return "* `has_in_" + self.safeAttributeName + "( " + self.singularName + " )`: `bool`\n * `" + self.singularName + "`: `" + self.typePolicy.documentTypeName() + "`\n"
return "* `has_in_" + self.safeAttributeName + "( " + self.singularName + " )`: `bool`\n * `" + self.singularName + "`: " + self.typePolicy.documentTypeName() + "\n"
class ElementCreatable( ListCapacity ):
def __init__( self, mandatoryParameters, optionalParameters, attributeModifiers = {} ):
@@ -85,7 +85,7 @@ class ElementCreatable( ListCapacity ):
return attributes
def autoDocument( self ):
return "* `create_" + self.singularName + "(" + self.__argumentsChecker.documentParameters() + ")`: `" + self.typePolicy.documentTypeName() + "`\n"
return "* `create_" + self.singularName + "(" + self.__argumentsChecker.documentParameters() + ")`: " + self.typePolicy.documentTypeName() + "\n"
class ElementGetable( ListCapacity ):
def __init__( self, mandatoryParameters, optionalParameters, attributeModifiers = {} ):
@@ -110,7 +110,7 @@ class ElementGetable( ListCapacity ):
return attributes
def autoDocument( self ):
return "* `get_" + self.singularName + "(" + self.__argumentsChecker.documentParameters() + ")`: `" + self.typePolicy.documentTypeName() + "`\n"
return "* `get_" + self.singularName + "(" + self.__argumentsChecker.documentParameters() + ")`: " + self.typePolicy.documentTypeName() + "\n"
class SeveralElementsAddable( ListCapacity ):
def apply( self, cls ):
@@ -128,7 +128,7 @@ class SeveralElementsAddable( ListCapacity ):
)
def autoDocument( self ):
return "* `add_to_" + self.safeAttributeName + "( " + self.singularName + ", .... )`\n * `" + self.singularName + "`: `" + self.typePolicy.documentTypeName() + "`\n"
return "* `add_to_" + self.safeAttributeName + "( " + self.singularName + ", ... )`\n * `" + self.singularName + "`: " + self.typePolicy.documentTypeName() + "\n"
class SeveralElementsRemovable( ListCapacity ):
def apply( self, cls ):
@@ -146,7 +146,7 @@ class SeveralElementsRemovable( ListCapacity ):
)
def autoDocument( self ):
return "* `remove_from_" + self.safeAttributeName + "( " + self.singularName + ", .... )`\n * `" + self.singularName + "`: `" + self.typePolicy.documentTypeName() + "`\n"
return "* `remove_from_" + self.safeAttributeName + "( " + self.singularName + ", ... )`\n * `" + self.singularName + "`: " + self.typePolicy.documentTypeName() + "\n"
class ListGetable( ListCapacity ):
def __init__( self, mandatoryParameters, optionalParameters, attributeModifiers = {} ):
@@ -172,7 +172,7 @@ class ListGetable( ListCapacity ):
]
def autoDocument( self ):
return "* `get_" + self.safeAttributeName + "(" + self.__argumentsChecker.documentParameters() + ")`: list of `" + self.typePolicy.documentTypeName() + "`\n"
return "* `get_" + self.safeAttributeName + "(" + self.__argumentsChecker.documentParameters() + ")`: list of " + self.typePolicy.documentTypeName() + "\n"
def __modifyAttributes( self, obj, attributes ):
for attributeName, attributeModifier in self.__attributeModifiers.iteritems():
@@ -195,7 +195,7 @@ class ListSetable( ListCapacity ):
)
def autoDocument( self ):
return "* `set_" + self.safeAttributeName + "( " + self.singularName + ", .... )`\n"
return "* `set_" + self.safeAttributeName + "( " + self.singularName + ", ... )`\n"
class ListDeletable( ListCapacity ):
def apply( self, cls ):
@@ -217,7 +217,7 @@ def ExternalListOfObjects( attributeName, singularName, type, *capacities ):
capacity.setList( attributeName, singularName, ObjectTypePolicy( type ) )
return SeveralAttributePolicies( capacities, attributeName.capitalize().replace( "_", " " ).replace( "/", " " ) )
def ExternalListOfSimpleTypes( attributeName, singularName, *capacities ):
def ExternalListOfSimpleTypes( attributeName, singularName, type, *capacities ):
for capacity in capacities:
capacity.setList( attributeName, singularName, SimpleTypePolicy() )
capacity.setList( attributeName, singularName, SimpleTypePolicy( type ) )
return SeveralAttributePolicies( capacities, attributeName.capitalize().replace( "_", " " ).replace( "/", " " ) )
github/ObjectCapacities/TypePolicies.py
+11 -3
View File
@@ -1,13 +1,18 @@
class SimpleTypePolicy:
def __init__( self, type ):
self.__type = type
def createLazy( self, obj, value ):
return value
def getIdentity( self, value ):
return value
def hasMeaningfulDocumentation( self ):
return self.__type is not None
def documentTypeName( self ):
### @todo
return "SHIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIT"
return self.__type
class ObjectTypePolicy:
def __init__( self, type ):
@@ -26,5 +31,8 @@ class ObjectTypePolicy:
assert isinstance( obj, self.__type )
return obj._identity
def hasMeaningfulDocumentation( self ):
return True
def documentTypeName( self ):
return self.__type.__name__
return "`" + self.__type.__name__ + "`"