Merge pull request #973 from fgebhart/docstring-triple-quotes-319

Replace single- with double-quote for docstrings, as per PEP-257

noxfile.py

@@ -95,7 +95,7 @@ def docs(session):
 
 @nox.session
 def watch(session):
-    '''Build and serve live docs for editing'''
+    """Build and serve live docs for editing"""
     session.install("-e", ".[docs]")
 
     session.run("mkdocs", "serve")
@@ -114,7 +114,7 @@ def examples(session):
 
 @nox.session
 def build(session):
-    '''Build package'''
+    """Build package"""
     # check preexisting
     exist_but_should_not = [p for p in BUILD_DIRS if Path(p).is_dir()]
     if exist_but_should_not:
@@ -129,21 +129,21 @@ def build(session):
 
 @nox.session
 def clean(session):
-    '''Remove build directories'''
+    """Remove build directories"""
     to_remove = [Path(d) for d in BUILD_DIRS if Path(d).is_dir()]
     for p in to_remove:
         shutil.rmtree(p)
 
 
 @nox.session
 def publish_testpypi(session):
-    '''Publish to TestPyPi using API token'''
+    """Publish to TestPyPi using API token"""
     _publish(session, 'testpypi')
 
 
 @nox.session
 def publish_pypi(session):
-    '''Publish to PyPi using API token'''
+    """Publish to PyPi using API token"""
     _publish(session, 'pypi')
 
 

planet/auth.py

@@ -12,7 +12,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-'''Manage authentication with Planet APIs'''
+"""Manage authentication with Planet APIs"""
 from __future__ import annotations  # https://stackoverflow.com/a/33533514
 import abc
 import json
@@ -38,15 +38,15 @@
 
 
 class Auth(metaclass=abc.ABCMeta):
-    '''Handle authentication information for use with Planet APIs.'''
+    """Handle authentication information for use with Planet APIs."""
 
     @staticmethod
     def from_key(key: str) -> AuthType:
-        '''Obtain authentication from api key.
+        """Obtain authentication from api key.
 
         Parameters:
             key: Planet API key
-        '''
+        """
         auth = APIKeyAuth(key=key)
         LOGGER.debug('Auth obtained from api key.')
         return auth
@@ -55,7 +55,7 @@ def from_key(key: str) -> AuthType:
     def from_file(
         filename: Optional[typing.Union[str,
                                         pathlib.Path]] = None) -> AuthType:
-        '''Create authentication from secret file.
+        """Create authentication from secret file.
 
         The secret file is named `.planet.json` and is stored in the user
         directory. The file has a special format and should have been created
@@ -64,7 +64,7 @@ def from_file(
         Parameters:
             filename: Alternate path for the planet secret file.
 
-        '''
+        """
         filename = filename or SECRET_FILE_PATH
 
         try:
@@ -80,13 +80,13 @@ def from_file(
 
     @staticmethod
     def from_env(variable_name: Optional[str] = None) -> AuthType:
-        '''Create authentication from environment variable.
+        """Create authentication from environment variable.
 
         Reads the `PL_API_KEY` environment variable
 
         Parameters:
             variable_name: Alternate environment variable.
-        '''
+        """
         variable_name = variable_name or ENV_API_KEY
         api_key = os.getenv(variable_name, '')
         try:
@@ -102,7 +102,7 @@ def from_env(variable_name: Optional[str] = None) -> AuthType:
     def from_login(email: str,
                    password: str,
                    base_url: Optional[str] = None) -> AuthType:
-        '''Create authentication from login email and password.
+        """Create authentication from login email and password.
 
         Note: To keep your password secure, the use of `getpass` is
         recommended.
@@ -112,7 +112,7 @@ def from_login(email: str,
             password: Planet account password.
             base_url: The base URL to use. Defaults to production
                 authentication API base url.
-        '''
+        """
         cl = AuthClient(base_url=base_url)
         auth_data = cl.login(email, password)
 
@@ -137,11 +137,11 @@ def to_dict(self) -> dict:
 
     def store(self,
               filename: Optional[typing.Union[str, pathlib.Path]] = None):
-        '''Store authentication information in secret file.
+        """Store authentication information in secret file.
 
         Parameters:
             filename: Alternate path for the planet secret file.
-        '''
+        """
         filename = filename or SECRET_FILE_PATH
         secret_file = _SecretFile(filename)
         secret_file.write(self.to_dict())
@@ -160,7 +160,7 @@ def __init__(self, base_url: Optional[str] = None):
             self._base_url = self._base_url[:-1]
 
     def login(self, email: str, password: str) -> dict:
-        '''Login using email identity and credentials.
+        """Login using email identity and credentials.
 
         Note: To keep your password secure, the use of `getpass` is
         recommended.
@@ -172,7 +172,7 @@ def login(self, email: str, password: str) -> dict:
         Returns:
              A JSON object containing an `api_key` property with the user's
         API_KEY.
-        '''
+        """
         url = f'{self._base_url}/login'
         data = {'email': email, 'password': password}
 
@@ -182,42 +182,42 @@ def login(self, email: str, password: str) -> dict:
 
     @staticmethod
     def decode_response(response):
-        '''Decode the token JWT'''
+        """Decode the token JWT"""
         token = response.json()['token']
         return jwt.decode(token, options={'verify_signature': False})
 
 
 class APIKeyAuthException(Exception):
-    '''exceptions thrown by APIKeyAuth'''
+    """exceptions thrown by APIKeyAuth"""
     pass
 
 
 class APIKeyAuth(httpx.BasicAuth, Auth):
-    '''Planet API Key authentication.'''
+    """Planet API Key authentication."""
     DICT_KEY = 'key'
 
     def __init__(self, key: str):
-        '''Initialize APIKeyAuth.
+        """Initialize APIKeyAuth.
 
         Parameters:
             key: API key.
 
         Raises:
             APIKeyException: If API key is None or empty string.
-        '''
+        """
         if not key:
             raise APIKeyAuthException('API key cannot be empty.')
         self._key = key
         super().__init__(self._key, '')
 
     @classmethod
     def from_dict(cls, data: dict) -> APIKeyAuth:
-        '''Instantiate APIKeyAuth from a dict.'''
+        """Instantiate APIKeyAuth from a dict."""
         api_key = data[cls.DICT_KEY]
         return cls(api_key)
 
     def to_dict(self):
-        '''Represent APIKeyAuth as a dict.'''
+        """Represent APIKeyAuth as a dict."""
         return {self.DICT_KEY: self._key}
 
     @property
@@ -262,7 +262,7 @@ def read(self) -> dict:
         return contents
 
     def _enforce_permissions(self):
-        '''if the file's permissions are not what they should be, fix them'''
+        """if the file's permissions are not what they should be, fix them"""
         if self.path.exists():
             # in octal, permissions is the last three bits of the mode
             file_permissions = self.path.stat().st_mode & 0o777

planet/cli/auth.py

@@ -31,7 +31,7 @@
               default=None,
               help='Assign custom base Auth API URL.')
 def auth(ctx, base_url):
-    '''Commands for working with Planet authentication'''
+    """Commands for working with Planet authentication"""
     ctx.obj['BASE_URL'] = base_url
 
 
@@ -47,7 +47,7 @@ def auth(ctx, base_url):
                        confirmation_prompt=False,
                        help=('Account password. Will not be saved.'))
 def init(ctx, email, password):
-    '''Obtain and store authentication information'''
+    """Obtain and store authentication information"""
     base_url = ctx.obj['BASE_URL']
     plauth = planet.Auth.from_login(email, password, base_url=base_url)
     plauth.store()
@@ -61,15 +61,15 @@ def init(ctx, email, password):
 @auth.command()
 @translate_exceptions
 def value():
-    '''Print the stored authentication information'''
+    """Print the stored authentication information"""
     click.echo(planet.Auth.from_file().value)
 
 
 @auth.command()
 @translate_exceptions
 @click.argument('key')
 def store(key):
-    '''Store authentication information'''
+    """Store authentication information"""
     plauth = planet.Auth.from_key(key)
     if click.confirm('This overrides the stored value. Continue?'):
         plauth.store()

planet/cli/data.py

@@ -56,7 +56,7 @@ async def data_client(ctx):
               default=None,
               help='Assign custom base Orders API URL.')
 def data(ctx, base_url):
-    '''Commands for interacting with the Data API'''
+    """Commands for interacting with the Data API"""
     ctx.obj['BASE_URL'] = base_url
 
 
@@ -71,8 +71,8 @@ def assets_to_filter(ctx, param, assets: List[str]) -> Optional[dict]:
 
 
 def check_item_types(ctx, param, item_types) -> Optional[List[dict]]:
-    '''Validates each item types provided by comparing them to all supported
-    item types.'''
+    """Validates each item types provided by comparing them to all supported
+    item types."""
     try:
         for item_type in item_types:
             validate_data_item_type(item_type)
@@ -82,8 +82,8 @@ def check_item_types(ctx, param, item_types) -> Optional[List[dict]]:
 
 
 def check_item_type(ctx, param, item_type) -> Optional[List[dict]]:
-    '''Validates the item type provided by comparing it to all supported
-    item types.'''
+    """Validates the item type provided by comparing it to all supported
+    item types."""
     try:
         validate_data_item_type(item_type)
     except SpecificationException as e:
@@ -93,7 +93,7 @@ def check_item_type(ctx, param, item_type) -> Optional[List[dict]]:
 
 
 def check_search_id(ctx, param, search_id) -> str:
-    '''Ensure search id is a valix hex string'''
+    """Ensure search id is a valix hex string"""
     try:
         _ = DataClient._check_search_id(search_id)
     except exceptions.ClientError as e:
@@ -580,7 +580,7 @@ async def asset_download(ctx,
 @click.argument("item_id")
 @click.argument("asset_type")
 async def asset_activate(ctx, item_type, item_id, asset_type):
-    '''Activate an asset.'''
+    """Activate an asset."""
     async with data_client(ctx) as cl:
         asset = await cl.get_asset(item_type, item_id, asset_type)
         await cl.activate_asset(asset)
@@ -603,11 +603,11 @@ async def asset_activate(ctx, item_type, item_id, asset_type):
               show_default=True,
               help='Maximum number of polls. Set to zero for no limit.')
 async def asset_wait(ctx, item_type, item_id, asset_type, delay, max_attempts):
-    '''Wait for an asset to be activated.
+    """Wait for an asset to be activated.
 
     Returns when the asset status has reached "activated" and the asset is
     available.
-    '''
+    """
     quiet = ctx.obj['QUIET']
     async with data_client(ctx) as cl:
         asset = await cl.get_asset(item_type, item_id, asset_type)
@@ -629,7 +629,7 @@ async def asset_wait(ctx, item_type, item_id, asset_type, delay, max_attempts):
 # @click.argument("asset_type_id")
 # @pretty
 # async def asset_get(ctx, item_type, item_id, asset_type_id, pretty):
-#     '''Get an item asset.'''
+#     """Get an item asset."""
 #     async with data_client(ctx) as cl:
 #         asset = await cl.get_asset(item_type, item_id, asset_type_id)
 #     echo_json(asset, pretty)

planet/cli/orders.py

@@ -44,7 +44,7 @@ async def orders_client(ctx):
               default=None,
               help='Assign custom base Orders API URL.')
 def orders(ctx, base_url):
-    '''Commands for interacting with the Orders API'''
+    """Commands for interacting with the Orders API"""
     ctx.obj['BASE_URL'] = base_url
 
 
@@ -59,14 +59,14 @@ def orders(ctx, base_url):
 @limit
 @pretty
 async def list(ctx, state, limit, pretty):
-    '''List orders
+    """List orders
 
     This command prints a sequence of the returned order descriptions,
     optionally pretty-printed.
 
     Order descriptions are sorted by creation date with the last created order
     returned first.
-    '''
+    """
     async with orders_client(ctx) as cl:
         async for o in cl.list_orders(state=state, limit=limit):
             echo_json(o, pretty)
@@ -95,11 +95,11 @@ async def get(ctx, order_id, pretty):
 @coro
 @click.argument('order_id', type=click.UUID)
 async def cancel(ctx, order_id):
-    '''Cancel order by order ID.
+    """Cancel order by order ID.
 
     This command cancels a queued order and outputs the cancelled order
     details.
-    '''
+    """
     async with orders_client(ctx) as cl:
         json_resp = await cl.cancel_order(str(order_id))
 
@@ -207,14 +207,14 @@ async def download(ctx, order_id, overwrite, directory, checksum):
 @click.argument("request", type=types.JSON())
 @pretty
 async def create(ctx, request: str, pretty):
-    '''Create an order.
+    """Create an order.
 
     This command outputs the created order description, optionally
     pretty-printed.
 
     REQUEST is the full description of the order to be created. It must be JSON
     and can be specified a json string, filename, or '-' for stdin.
-    '''
+    """
     async with orders_client(ctx) as cl:
         order = await cl.create_order(request)