Skip to content

Commit

Permalink
Merge pull request googleapis#948 from dhermes/add-pylint-docstring-c…
Browse files Browse the repository at this point in the history
…hecker

Adding Pylint plugin to check Sphinx docstrings.
  • Loading branch information
dhermes committed Jun 25, 2015
2 parents 119cba3 + aaee908 commit 7dece69
Show file tree
Hide file tree
Showing 19 changed files with 116 additions and 73 deletions.
12 changes: 12 additions & 0 deletions gcloud/connection.py
Original file line number Diff line number Diff line change
Expand Up @@ -127,6 +127,12 @@ def from_service_account_json(cls, json_credentials_path, *args, **kwargs):
other credentials information (downloaded
from the Google APIs console).
:type args: tuple
:param args: Remaining positional arguments to pass to constructor.
:type kwargs: dictionary
:param kwargs: Remaining keyword arguments to pass to constructor.
:rtype: :class:`gcloud.connection.Connection`
:returns: The connection created with the retrieved JSON credentials.
"""
Expand All @@ -153,6 +159,12 @@ def from_service_account_p12(cls, client_email, private_key_path,
given to you when you created the service
account). This file must be in P12 format.
:type args: tuple
:param args: Remaining positional arguments to pass to constructor.
:type kwargs: dictionary
:param kwargs: Remaining keyword arguments to pass to constructor.
:rtype: :class:`gcloud.connection.Connection`
:returns: The connection created with the retrieved P12 credentials.
"""
Expand Down
11 changes: 4 additions & 7 deletions gcloud/credentials.py
Original file line number Diff line number Diff line change
Expand Up @@ -208,20 +208,17 @@ def _get_service_account_name(credentials):
:param credentials: The credentials used to determine the service
account name.
:type string_to_sign: string
:param string_to_sign: The string to be signed by the credentials.
:rtype: bytes
:returns: Signed bytes produced by the credentials.
:rtype: string
:returns: Service account name associated with the credentials.
:raises: :class:`ValueError` if the credentials are not a valid service
account type
account type.
"""
service_account_name = None
if isinstance(credentials, client.SignedJwtAssertionCredentials):
service_account_name = credentials.service_account_name
elif isinstance(credentials, service_account._ServiceAccountCredentials):
service_account_name = credentials._service_account_email
elif _GAECreds is not None and isinstance(credentials, _GAECreds):
elif isinstance(credentials, _GAECreds):
service_account_name = app_identity.get_service_account_name()

if service_account_name is None:
Expand Down
4 changes: 4 additions & 0 deletions gcloud/datastore/_implicit_environ.py
Original file line number Diff line number Diff line change
Expand Up @@ -151,6 +151,10 @@ class _DefaultsContainer(object):
:type dataset_id: string
:param dataset_id: Persistent implied dataset ID from environment.
:type implicit: boolean
:param implicit: Boolean indicating if the container should allow
implicit properties.
"""

@_lazy_property_deco
Expand Down
28 changes: 13 additions & 15 deletions gcloud/datastore/batch.py
Original file line number Diff line number Diff line change
Expand Up @@ -61,21 +61,19 @@ class Batch(object):
>>> with Batch() as batch:
... do_some_work(batch)
... raise Exception() # rolls back
"""
_id = None # "protected" attribute, always None for non-transactions
def __init__(self, dataset_id=None, connection=None):
"""Construct a batch.
:type dataset_id: :class:`str`.
:param dataset_id: The ID of the dataset.
:type dataset_id: :class:`str`.
:param dataset_id: The ID of the dataset.
:type connection: :class:`gcloud.datastore.connection.Connection`
:param connection: The connection used to connect to datastore.
:type connection: :class:`gcloud.datastore.connection.Connection`
:param connection: The connection used to connect to datastore.
:raises: :class:`ValueError` if either a connection or dataset ID
are not set.
"""
_id = None # "protected" attribute, always None for non-transactions

:raises: :class:`ValueError` if either a connection or dataset ID
are not set.
"""
def __init__(self, dataset_id=None, connection=None):
self._connection = (connection or
_implicit_environ.get_default_connection())
self._dataset_id = (dataset_id or
Expand Down Expand Up @@ -254,14 +252,14 @@ def _assign_entity_to_mutation(mutation_pb, entity, auto_id_entities):
Helper method for ``Batch.put``.
:type mutation_pb: :class:`gcloud.datastore._datastore_v1_pb2.Mutation`
:param mutation_pb; the Mutation protobuf for the batch / transaction.
:param mutation_pb: The Mutation protobuf for the batch / transaction.
:type entity: :class:`gcloud.datastore.entity.Entity`
:param entity; the entity being updated within the batch / transaction.
:param entity: The entity being updated within the batch / transaction.
:type auto_id_entities: list of :class:`gcloud.datastore.entity.Entity`
:param auto_id_entities: entiites with partial keys, to be fixed up
during commit.
:param auto_id_entities: Entities with partial keys, to be fixed up
during commit.
"""
auto_id = entity.key.is_partial

Expand Down
3 changes: 3 additions & 0 deletions gcloud/datastore/connection.py
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,9 @@ class Connection(connection.Connection):
:type credentials: :class:`oauth2client.client.OAuth2Credentials`
:param credentials: The OAuth2 Credentials to use for this connection.
:type http: :class:`httplib2.Http` or class that defines ``request()``.
:param http: An optional HTTP object to make requests.
:type api_base_url: string
:param api_base_url: The base of the API call URL. Defaults to the value
from :mod:`gcloud.connection`.
Expand Down
39 changes: 20 additions & 19 deletions gcloud/datastore/key.py
Original file line number Diff line number Diff line change
Expand Up @@ -43,29 +43,22 @@ class Key(object):
>>> Key('Parent', 'foo', 'Child')
<Key[{'kind': 'Parent', 'name': 'foo'}, {'kind': 'Child'}]>
.. automethod:: __init__
"""

def __init__(self, *path_args, **kwargs):
"""Constructor / initializer for a key.
:type path_args: tuple of string and integer
:param path_args: May represent a partial (odd length) or full (even
length) key path.
:type path_args: tuple of string and integer
:param path_args: May represent a partial (odd length) or full (even
length) key path.
:type kwargs: dictionary
:param kwargs: Keyword arguments to be passed in.
:type namespace: string
:param namespace: A namespace identifier for the key. Can only be
passed as a keyword argument.
Accepted keyword arguments are
* namespace (string): A namespace identifier for the key.
* dataset_id (string): The dataset ID associated with the key.
* parent (:class:`gcloud.datastore.key.Key`): The parent of the key.
:type dataset_id: string
:param dataset_id: The dataset ID associated with the key. Required,
unless the implicit dataset ID has been set. Can
only be passed as a keyword argument.
The dataset ID argument is required unless it has been set implicitly.
"""

:type parent: :class:`gcloud.datastore.key.Key`
:param parent: The parent of the key. Can only be passed as a
keyword argument.
"""
def __init__(self, *path_args, **kwargs):
self._flat_path = path_args
parent = self._parent = kwargs.get('parent')
self._namespace = kwargs.get('namespace')
Expand Down Expand Up @@ -393,6 +386,14 @@ def _validate_dataset_id(dataset_id, parent):
If ``dataset_id`` is unset, attempt to infer the ID from the environment.
:type dataset_id: string
:param dataset_id: A dataset ID.
:type parent: :class:`gcloud.datastore.key.Key` or ``NoneType``
:param parent: The parent of the key or ``None``.
:rtype: string
:returns: The ``dataset_id`` passed in, or implied from the environment.
:raises: :class:`ValueError` if ``dataset_id`` is ``None`` and no dataset
can be inferred.
"""
Expand Down
3 changes: 3 additions & 0 deletions gcloud/iterator.py
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,9 @@ class Iterator(object):
:type path: string
:param path: The path to query for the list of items.
:type extra_params: dict or None
:param extra_params: Extra query string parameters for the API call.
"""

PAGE_TOKEN = 'pageToken'
Expand Down
9 changes: 5 additions & 4 deletions gcloud/pubsub/message.py
Original file line number Diff line number Diff line change
Expand Up @@ -28,14 +28,15 @@ class Message(object):
See:
https://cloud.google.com/pubsub/reference/rest/google/pubsub/v1beta2/PubsubMessage
:type name: bytes
:param name: the payload of the message
:type data: bytes
:param data: the payload of the message
:type message_id: string
:param message_id: An ID assigned to the message by the API.
:type attrs: dict or None
:param attrs: Extra metadata associated by the publisher with the message.
:type attributes: dict or None
:param attributes: Extra metadata associated by the publisher with the
message.
"""
def __init__(self, data, message_id, attributes=None):
self.data = data
Expand Down
4 changes: 2 additions & 2 deletions gcloud/pubsub/topic.py
Original file line number Diff line number Diff line change
Expand Up @@ -156,7 +156,7 @@ def publish(self, message, client=None, **attrs):
``client`` stored on the current topic.
:type attrs: dict (string -> string)
:message attrs: key-value pairs to send as message attributes
:param attrs: key-value pairs to send as message attributes
:rtype: str
:returns: message ID assigned by the server to the published message
Expand Down Expand Up @@ -232,7 +232,7 @@ def publish(self, message, **attrs):
:param message: the message payload
:type attrs: dict (string -> string)
:message attrs: key-value pairs to send as message attributes
:param attrs: key-value pairs to send as message attributes
"""
self.topic._timestamp_message(attrs)
self.messages.append(
Expand Down
15 changes: 10 additions & 5 deletions gcloud/storage/_helpers.py
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,9 @@ class _PropertyMixin(object):
Non-abstract subclasses should implement:
- connection
- path
:type name: string
:param name: The name of the object.
"""

@property
Expand All @@ -38,11 +41,6 @@ def path(self):
raise NotImplementedError

def __init__(self, name=None):
"""_PropertyMixin constructor.
:type name: string
:param name: The name of the object.
"""
self.name = name
self._properties = {}
self._changes = set()
Expand Down Expand Up @@ -156,6 +154,13 @@ def _write_buffer_to_hash(buffer_object, hash_obj, digest_block_size=8192):
:type buffer_object: bytes buffer
:param buffer_object: Buffer containing bytes used to update a hash object.
:type hash_obj: object that implements update
:param hash_obj: A hash object (MD5 or CRC32-C).
:type digest_block_size: integer
:param digest_block_size: The block size to write to the hash.
Defaults to 8192.
"""
block = buffer_object.read(digest_block_size)

Expand Down
4 changes: 4 additions & 0 deletions gcloud/storage/_implicit_environ.py
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,10 @@ class _DefaultsContainer(object):
:type connection: :class:`gcloud.storage.connection.Connection`
:param connection: Persistent implied connection from environment.
:type implicit: boolean
:param implicit: Boolean indicating if the container should allow
implicit properties.
"""

@_lazy_property_deco
Expand Down
26 changes: 12 additions & 14 deletions gcloud/storage/acl.py
Original file line number Diff line number Diff line change
Expand Up @@ -86,22 +86,20 @@ class _ACLEntity(object):
This is a helper class that you likely won't ever construct
outside of using the factor methods on the :class:`ACL` object.
:type entity_type: string
:param entity_type: The type of entity (ie, 'group' or 'user').
:type identifier: string
:param identifier: The ID or e-mail of the entity. For the special
entity types (like 'allUsers') this is optional.
"""

READER_ROLE = 'READER'
WRITER_ROLE = 'WRITER'
OWNER_ROLE = 'OWNER'

def __init__(self, entity_type, identifier=None):
"""Entity constructor.
:type entity_type: string
:param entity_type: The type of entity (ie, 'group' or 'user').
:type identifier: string
:param identifier: The ID or e-mail of the entity. For the special
entity types (like 'allUsers') this is optional.
"""
self.identifier = identifier
self.roles = set([])
self.type = entity_type
Expand Down Expand Up @@ -416,13 +414,13 @@ def clear(self, connection=None):


class BucketACL(ACL):
"""An ACL specifically for a bucket."""
"""An ACL specifically for a bucket.
:type bucket: :class:`gcloud.storage.bucket.Bucket`
:param bucket: The bucket to which this ACL relates.
"""

def __init__(self, bucket):
"""
:type bucket: :class:`gcloud.storage.bucket.Bucket`
:param bucket: The bucket to which this ACL relates.
"""
super(BucketACL, self).__init__()
self.bucket = bucket

Expand Down
3 changes: 3 additions & 0 deletions gcloud/storage/api.py
Original file line number Diff line number Diff line change
Expand Up @@ -207,6 +207,9 @@ class _BucketIterator(Iterator):
:type connection: :class:`gcloud.storage.connection.Connection`
:param connection: The connection to use for querying the list of buckets.
:type extra_params: dict or ``NoneType``
:param extra_params: Extra query string parameters for the API call.
"""

def __init__(self, connection, extra_params=None):
Expand Down
12 changes: 12 additions & 0 deletions gcloud/storage/batch.py
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,12 @@ class MIMEApplicationHTTP(MIMEApplication):
Constructs payload from headers and body
:type method: string
:param method: HTTP method
:type uri: string
:param uri: URI for HTTP request
:type headers: dict
:param headers: HTTP headers
Expand Down Expand Up @@ -155,6 +161,12 @@ def _do_request(self, method, url, headers, data, target_object):
:type data: string
:param data: The data to send as the body of the request.
:type target_object: object or :class:`NoneType`
:param target_object: This allows us to enable custom behavior in our
batch connection. Here we defer an HTTP request
and complete initialization of the object at a
later time.
:rtype: tuple of ``response`` (a dictionary of sorts)
and ``content`` (a string).
:returns: The HTTP response object and the content of the response.
Expand Down
7 changes: 4 additions & 3 deletions gcloud/storage/blob.py
Original file line number Diff line number Diff line change
Expand Up @@ -57,9 +57,6 @@ class Blob(_PropertyMixin):
:param chunk_size: The size of a chunk of data whenever iterating (1 MB).
This must be a multiple of 256 KB per the API
specification.
:type properties: dict
:param properties: All the other data provided by Cloud Storage.
"""

_chunk_size = None # Default value for each instance.
Expand Down Expand Up @@ -507,6 +504,10 @@ def upload_from_string(self, data, content_type='text/plain',
:param data: The data to store in this blob. If the value is
text, it will be encoded as UTF-8.
:type content_type: string
:param content_type: Optional type of content being uploaded. Defaults
to ``'text/plain'``.
:type connection: :class:`gcloud.storage.connection.Connection` or
``NoneType``
:param connection: Optional. The connection to use when sending
Expand Down
3 changes: 0 additions & 3 deletions gcloud/storage/bucket.py
Original file line number Diff line number Diff line change
Expand Up @@ -78,9 +78,6 @@ class Bucket(_PropertyMixin):
:type name: string
:param name: The name of the bucket.
:type properties: dictionary or ``NoneType``
:param properties: The properties associated with the bucket.
"""
_iterator_class = _BlobIterator

Expand Down
3 changes: 3 additions & 0 deletions pylintrc_default
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,9 @@ ignore =
# List of plugins (as comma separated values of python modules names) to load,
# usually to register additional checkers.
# DEFAULT: load-plugins=
# RATIONALE: We want to make sure our docstrings match the objects
# they document.
load-plugins=pylint.extensions.check_docs

# DEPRECATED
# DEFAULT: include-ids=no
Expand Down
Loading

0 comments on commit 7dece69

Please sign in to comment.