diff --git a/docs/dns-resource_record_set.rst b/docs/dns-resource-record-set.rst similarity index 100% rename from docs/dns-resource_record_set.rst rename to docs/dns-resource-record-set.rst diff --git a/docs/index.rst b/docs/index.rst index b62f2774872d..e97e005076d6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -67,7 +67,7 @@ dns-usage Client dns-zone - dns-resource_record_set + dns-resource-record-set dns-changes .. toctree:: @@ -115,7 +115,7 @@ try installing the ``dev`` packages beforehand: $ sudo apt-get install python-dev libssl-dev -If you want to install `gcloud-python` from source, +If you want to install ``gcloud-python`` from source, you can clone the repository from GitHub: .. code-block:: console diff --git a/gcloud/bigquery/client.py b/gcloud/bigquery/client.py index 0870837bdde8..0927a03cacc7 100644 --- a/gcloud/bigquery/client.py +++ b/gcloud/bigquery/client.py @@ -151,11 +151,15 @@ def list_jobs(self, max_results=None, page_token=None, all_users=None, :type state_filter: string :param state_filter: if passed, include only jobs matching the given - state. One of "done", "pending", or "running". + state. One of + + * ``"done"`` + * ``"pending"`` + * ``"running"`` :rtype: tuple, (list, str) :returns: list of job instances, plus a "next page token" string: - if the token is not None, indicates that more jobs can be + if the token is not ``None``, indicates that more jobs can be retrieved with another call, passing that value as ``page_token``). """ diff --git a/gcloud/bigquery/dataset.py b/gcloud/bigquery/dataset.py index d1ba43bcdca7..2a4f545ebc3c 100644 --- a/gcloud/bigquery/dataset.py +++ b/gcloud/bigquery/dataset.py @@ -23,12 +23,19 @@ class AccessGrant(object): """Represent grant of an access role to an entity. - :type role: string (one of 'OWNER', 'WRITER', 'READER'). - :param role: role granted to the entity. + :type role: string + :param role: Role granted to the entity. One of - :type entity_type: string (one of 'specialGroup', 'groupByEmail', or - 'userByEmail') - :param entity_type: type of entity being granted the role. + * ``'OWNER'`` + * ``'WRITER'`` + * ``'READER'`` + + :type entity_type: string + :param entity_type: Type of entity being granted the role. One of + + * ``'specialGroup'`` + * ``'groupByEmail'`` + * ``'userByEmail'`` :type entity_id: string :param entity_id: ID of entity being granted the role. @@ -360,7 +367,7 @@ def create(self, client=None): """API call: create the dataset via a PUT request See: - https://cloud.google.com/bigquery/reference/rest/v2/tables/insert + https://cloud.google.com/bigquery/docs/reference/v2/tables/insert :type client: :class:`gcloud.bigquery.client.Client` or ``NoneType`` :param client: the client to use. If not passed, falls back to the @@ -465,7 +472,7 @@ def delete(self, client=None): """API call: delete the dataset via a DELETE request See: - https://cloud.google.com/bigquery/reference/rest/v2/datasets/delete + https://cloud.google.com/bigquery/docs/reference/v2/tables/delete :type client: :class:`gcloud.bigquery.client.Client` or ``NoneType`` :param client: the client to use. If not passed, falls back to the @@ -491,7 +498,7 @@ def list_tables(self, max_results=None, page_token=None): :rtype: tuple, (list, str) :returns: list of :class:`gcloud.bigquery.table.Table`, plus a - "next page token" string: if not None, indicates that + "next page token" string: if not ``None``, indicates that more tables can be retrieved with another call (pass that value as ``page_token``). """ diff --git a/gcloud/bigtable/table.py b/gcloud/bigtable/table.py index 8edcd6f8e992..c43c7879d152 100644 --- a/gcloud/bigtable/table.py +++ b/gcloud/bigtable/table.py @@ -192,9 +192,10 @@ def delete(self): def list_column_families(self): """List the column families owned by this table. - :rtype: dictionary with string as keys and - :class:`.column_family.ColumnFamily` as values - :returns: List of column families attached to this table. + :rtype: dict + :returns: Dictionary of column families attached to this table. Keys + are strings (column family names) and values are + :class:`.column_family.ColumnFamily` instances. :raises: :class:`ValueError ` if the column family name from the response does not agree with the computed name from the column family ID. diff --git a/gcloud/client.py b/gcloud/client.py index 31aa3c48b690..2e7e02a3e40d 100644 --- a/gcloud/client.py +++ b/gcloud/client.py @@ -46,12 +46,12 @@ def from_service_account_json(cls, json_credentials_path, *args, **kwargs): :type args: tuple :param args: Remaining positional arguments to pass to constructor. - :type kwargs: dictionary + :type kwargs: dict :param kwargs: Remaining keyword arguments to pass to constructor. :rtype: :class:`gcloud.pubsub.client.Client` :returns: The client created with the retrieved JSON credentials. - :raises: class:`TypeError` if there is a conflict with the kwargs + :raises: :class:`TypeError` if there is a conflict with the kwargs and the credentials created by the factory. """ if 'credentials' in kwargs: @@ -80,12 +80,12 @@ def from_service_account_p12(cls, client_email, private_key_path, :type args: tuple :param args: Remaining positional arguments to pass to constructor. - :type kwargs: dictionary + :type kwargs: dict :param kwargs: Remaining keyword arguments to pass to constructor. :rtype: :class:`gcloud.client.Client` :returns: The client created with the retrieved P12 credentials. - :raises: class:`TypeError` if there is a conflict with the kwargs + :raises: :class:`TypeError` if there is a conflict with the kwargs and the credentials created by the factory. """ if 'credentials' in kwargs: diff --git a/gcloud/connection.py b/gcloud/connection.py index 8aff8d5901ad..16929eec5684 100644 --- a/gcloud/connection.py +++ b/gcloud/connection.py @@ -124,15 +124,18 @@ class JSONConnection(Connection): """A connection to a Google JSON-based API. These APIs are discovery based. For reference: + https://developers.google.com/discovery/ - This defines :meth:`Connection.api_request` for making a generic JSON + This defines :meth:`api_request` for making a generic JSON API request and API requests are created elsewhere. The class constants - * ``API_BASE_URL`` - * ``API_VERSION`` - * ``API_URL_TEMPLATE`` + + * :attr:`API_BASE_URL` + * :attr:`API_VERSION` + * :attr:`API_URL_TEMPLATE` + must be updated by subclasses. """ @@ -303,12 +306,12 @@ def api_request(self, method, path, query_params=None, latest API version supported by gcloud-python. - :type expect_json: boolean + :type expect_json: bool :param expect_json: If True, this method will try to parse the response as JSON and raise an exception if that cannot be done. Default is True. - :type _target_object: object or :class:`NoneType` + :type _target_object: :class:`object` or :class:`NoneType` :param _target_object: Protected argument to be used by library callers. This can allow custom behavior, for example, to defer an HTTP request and complete diff --git a/gcloud/credentials.py b/gcloud/credentials.py index cd61b7ff1955..61b8fdfbdb2c 100644 --- a/gcloud/credentials.py +++ b/gcloud/credentials.py @@ -46,38 +46,51 @@ def get_credentials(): """Gets credentials implicitly from the current environment. .. note:: - You should not need to use this function directly. Instead, use the - helper method :func:`gcloud.datastore.__init__.get_connection` - which uses this method under the hood. + + You should not need to use this function directly. Instead, use a + helper method which uses this method under the hood. Checks environment in order of precedence: * Google App Engine (production and testing) - * Environment variable GOOGLE_APPLICATION_CREDENTIALS pointing to + * Environment variable :envvar:`GOOGLE_APPLICATION_CREDENTIALS` pointing to a file with stored credentials information. * Stored "well known" file associated with ``gcloud`` command line tool. * Google Compute Engine production environment. - The file referred to in GOOGLE_APPLICATION_CREDENTIALS is expected to - contain information about credentials that are ready to use. This means - either service account information or user account information with - a ready-to-use refresh token:: + The file referred to in :envvar:`GOOGLE_APPLICATION_CREDENTIALS` is + expected to contain information about credentials that are ready to use. + This means either service account information or user account information + with a ready-to-use refresh token: + + .. code:: json + + { + 'type': 'authorized_user', + 'client_id': '...', + 'client_secret': '...', + 'refresh_token': '...' + } - { { - 'type': 'authorized_user', 'type': 'service_account', - 'client_id': '...', 'client_id': '...', - 'client_secret': '...', OR 'client_email': '...', - 'refresh_token': '..., 'private_key_id': '...', - } 'private_key': '...', - } + or + + .. code:: json + + { + 'type': 'service_account', + 'client_id': '...', + 'client_email': '...', + 'private_key_id': '...', + 'private_key': '...' + } The second of these is simply a JSON key downloaded from the Google APIs console. The first is a close cousin of the "client secrets" JSON file - used by ``oauth2client.clientsecrets`` but differs in formatting. + used by :mod:`oauth2client.clientsecrets` but differs in formatting. :rtype: :class:`oauth2client.client.GoogleCredentials`, - :class:`oauth2client.appengine.AppAssertionCredentials`, - :class:`oauth2client.gce.AppAssertionCredentials`, + :class:`oauth2client.contrib.appengine.AppAssertionCredentials`, + :class:`oauth2client.contrib.gce.AppAssertionCredentials`, :class:`oauth2client.service_account._ServiceAccountCredentials` :returns: A new credentials instance corresponding to the implicit environment. @@ -119,7 +132,7 @@ def get_for_service_account_p12(client_email, private_key_path, scope=None): .. note:: This method is not used by default, instead :func:`get_credentials` - is used. This method is intended to be used when the environments is + is used. This method is intended to be used when the environment is known explicitly and detecting the environment implicitly would be superfluous. @@ -302,7 +315,8 @@ def generate_signed_url(credentials, resource, expiration, :param resource: A pointer to a specific resource (typically, ``/bucket-name/path/to/blob.txt``). - :type expiration: int, long, datetime.datetime, datetime.timedelta + :type expiration: :class:`int`, :class:`long`, :class:`datetime.datetime`, + :class:`datetime.timedelta` :param expiration: When the signed URL should expire. :type api_access_endpoint: string diff --git a/gcloud/exceptions.py b/gcloud/exceptions.py index c2374ca58891..496940c4409e 100644 --- a/gcloud/exceptions.py +++ b/gcloud/exceptions.py @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Custom exceptions for gcloud.storage package. +"""Custom exceptions for :mod:`gcloud` package. See: https://cloud.google.com/storage/docs/json_api/v1/status-codes """ @@ -171,7 +171,7 @@ def make_exception(response, content, error_info=None, use_json=True): :param error_info: Optional string giving extra information about the failed request. - :type use_json: boolean + :type use_json: bool :param use_json: Flag indicating if ``content`` is expected to be JSON. :rtype: instance of :class:`GCloudError`, or a concrete subclass. @@ -213,7 +213,7 @@ def _walk_subclasses(klass): # Build the code->exception class mapping. -for eklass in _walk_subclasses(GCloudError): - code = getattr(eklass, 'code', None) +for _eklass in _walk_subclasses(GCloudError): + code = getattr(_eklass, 'code', None) if code is not None: - _HTTP_CODE_TO_EXCEPTION[code] = eklass + _HTTP_CODE_TO_EXCEPTION[code] = _eklass diff --git a/scripts/run_pylint.py b/scripts/run_pylint.py index 8f9c0fe25f97..8e2c7d302d9e 100644 --- a/scripts/run_pylint.py +++ b/scripts/run_pylint.py @@ -104,7 +104,7 @@ def valid_filename(filename): def is_production_filename(filename): """Checks if the file contains production code. - :rtype: boolean + :rtype: bool :returns: Boolean indicating production status. """ return not ('demo' in filename or 'test' in filename) @@ -127,7 +127,7 @@ def get_files_for_linting(allow_limited=True): ``GCLOUD_REMOTE_FOR_LINT`` and ``GCLOUD_BRANCH_FOR_LINT`` can be set to specify a remote branch to diff against. - :type allow_limited: boolean + :type allow_limited: bool :param allow_limited: Boolean indicating if a reduced set of files can be used.