Merge pull request astropy#507 from bsipocz/MAINT_kwarg_only

API: changing optional arguments to be keyword only

CHANGES.rst

@@ -4,6 +4,8 @@
 Enhancements and Fixes
 ----------------------
 
+- Making optional parameters keyword only throughout the public API. [#507]
+
 
 Deprecations and Removals
 -------------------------

pyvo/dal/adhoc.py

@@ -107,7 +107,7 @@ class AdhocServiceResultsMixin:
     Mixing for adhoc:service functionallity for results classes.
     """
 
-    def __init__(self, votable, url=None, session=None):
+    def __init__(self, votable, *, url=None, session=None):
         super().__init__(votable, url=url, session=session)
 
         self._adhocservices = list(
@@ -281,7 +281,7 @@ def __init__(self, baseurl, session=None):
         if hasattr(self._session, 'update_from_capabilities'):
             self._session.update_from_capabilities(self.capabilities)
 
-    def run_sync(self, id, responseformat=None, **keywords):
+    def run_sync(self, id, *, responseformat=None, **keywords):
         """
         runs sync query and returns its result
 
@@ -306,7 +306,7 @@ def run_sync(self, id, responseformat=None, **keywords):
     # alias for service discovery
     search = run_sync
 
-    def create_query(self, id, responseformat=None, **keywords):
+    def create_query(self, id, *, responseformat=None, **keywords):
         """
         create a query object that constraints can be added to and then
         executed.  The input arguments will initialize the query with the
@@ -347,7 +347,7 @@ class DatalinkQuery(DALQuery):
     allowing the caller to take greater control of the result processing.
     """
     @classmethod
-    def from_resource(cls, rows, resource, session=None, **kwargs):
+    def from_resource(cls, rows, resource, *, session=None, **kwargs):
         """
         Creates a instance from a number of records and a Datalink Resource.
 
@@ -406,7 +406,7 @@ def from_resource(cls, rows, resource, session=None, **kwargs):
         return cls(accessurl, session=session, **query_params)
 
     def __init__(
-            self, baseurl, id=None, responseformat=None, session=None, **keywords):
+            self, baseurl, *, id=None, responseformat=None, session=None, **keywords):
         """
         initialize the query object with the given parameters
 
@@ -519,7 +519,7 @@ def getrecord(self, index):
         """
         return DatalinkRecord(self, index, session=self._session)
 
-    def bysemantics(self, semantics, include_narrower=True):
+    def bysemantics(self, semantics, *, include_narrower=True):
         """
         return the rows with the dataset identified by the given semantics
 
@@ -600,7 +600,7 @@ def clone_byid(self, id):
                 copy_tb.resources.remove(x)
         return DatalinkResults(copy_tb)
 
-    def getdataset(self, timeout=None):
+    def getdataset(self, *, timeout=None):
         """
         return the first row with the dataset identified by semantics #this
 
@@ -675,7 +675,7 @@ def _get_soda_resource(self):
         return None
 
     def processed(
-            self, circle=None, range=None, polygon=None, band=None, **kwargs):
+            self, *, circle=None, range=None, polygon=None, band=None, **kwargs):
         """
         Returns processed dataset.
 
@@ -860,7 +860,7 @@ class SodaQuery(DatalinkQuery, AxisParamMixin):
     """
 
     def __init__(
-            self, baseurl, circle=None, range=None, polygon=None, band=None,
+            self, baseurl, *, circle=None, range=None, polygon=None, band=None,
             **kwargs):
         super().__init__(baseurl, **kwargs)
 

pyvo/dal/mimetype.py

@@ -53,7 +53,7 @@ def mime2extension(mimetype, default=None):
     return ext
 
 
-def mime_object_maker(url, mimetype, session=None):
+def mime_object_maker(url, mimetype, *, session=None):
     """
     return a data object suitable for the mimetype given.
     this will either return a astropy fits object or a pyvo DALResults object,

pyvo/dal/query.py

@@ -53,7 +53,7 @@ class DALService:
     endpoint.
     """
 
-    def __init__(self, baseurl, session=None):
+    def __init__(self, baseurl, *, session=None):
         """
         instantiate the service connecting it to a base URL
 
@@ -131,7 +131,7 @@ class DALQuery(dict):
 
     _ex = None
 
-    def __init__(self, baseurl, session=None, **keywords):
+    def __init__(self, baseurl, *, session=None, **keywords):
         """
         initialize the query object with a baseurl
         """
@@ -183,7 +183,7 @@ def execute_raw(self):
         return out
 
     @stream_decode_content
-    def execute_stream(self, post=False):
+    def execute_stream(self, *, post=False):
         """
         Submit the query and return the raw response as a file stream.
 
@@ -200,7 +200,7 @@ def execute_stream(self, post=False):
         finally:
             return response.raw
 
-    def submit(self, post=False):
+    def submit(self, *, post=False):
         """
         does the actual request
         """
@@ -215,7 +215,7 @@ def submit(self, post=False):
                                          allow_redirects=True)
         return response
 
-    def execute_votable(self, post=False):
+    def execute_votable(self, *, post=False):
         """
         Submit the query and return the results as an AstroPy votable instance.
         As this is the level where qualified error messages are available,
@@ -275,7 +275,7 @@ def _from_result_url(cls, result_url, session):
         return session.get(result_url, stream=True).raw
 
     @classmethod
-    def from_result_url(cls, result_url, session=None):
+    def from_result_url(cls, result_url, *, session=None):
         """
         Create a result object from a url.
 
@@ -287,7 +287,7 @@ def from_result_url(cls, result_url, session=None):
             url=result_url,
             session=session)
 
-    def __init__(self, votable, url=None, session=None):
+    def __init__(self, votable, *, url=None, session=None):
         """
         initialize the cursor.  This constructor is not typically called
         by directly applications; rather an instance is obtained from calling
@@ -626,7 +626,7 @@ def __iter__(self):
             yield out
             pos += 1
 
-    def broadcast_samp(self, client_name=None):
+    def broadcast_samp(self, *, client_name=None):
         """
         Broadcast the table to ``client_name`` via SAMP
         """
@@ -652,7 +652,7 @@ class Record(Mapping):
     additional functions for access to service type-specific data.
     """
 
-    def __init__(self, results, index, session=None):
+    def __init__(self, results, index, *, session=None):
         self._results = results
         self._index = index
         self._session = use_session(session)
@@ -790,7 +790,7 @@ def getdataset(self, timeout=None):
 
         return response.raw
 
-    def cachedataset(self, filename=None, dir=".", timeout=None, bufsize=None):
+    def cachedataset(self, *, filename=None, dir=".", timeout=None, bufsize=None):
         """
         retrieve the dataset described by this record and write it out to
         a file with the given name.  If the file already exists, it will be
@@ -844,7 +844,7 @@ def cachedataset(self, filename=None, dir=".", timeout=None, bufsize=None):
 
     _dsname_no = 0  # used by make_dataset_filename
 
-    def make_dataset_filename(self, dir=".", base=None, ext=None):
+    def make_dataset_filename(self, *, dir=".", base=None, ext=None):
         """
         create a viable pathname in a given directory for saving the dataset
         available via getdataset().  The pathname that is returned is
@@ -916,7 +916,7 @@ def suggest_dataset_basename(self):
         # abstract; specialized for the different service types
         return "dataset"
 
-    def suggest_extension(self, default=None):
+    def suggest_extension(self, *, default=None):
         """
         returns a recommended filename extension for the dataset described
         by this record.  Typically, this would look at the column describing

pyvo/dal/scs.py

@@ -33,7 +33,7 @@ class can represent a specific service available at a URL endpoint.
 __all__ = ["search", "SCSService", "SCSQuery", "SCSResults", "SCSRecord"]
 
 
-def search(url, pos, radius=1.0, verbosity=2, **keywords):
+def search(url, pos, *, radius=1.0, verbosity=2, **keywords):
     """
     submit a simple Cone Search query that requests objects or observations
     whose positions fall within some distance from a search position.
@@ -87,7 +87,7 @@ class SCSService(DALService):
     a representation of a Cone Search service
     """
 
-    def __init__(self, baseurl, session=None):
+    def __init__(self, baseurl, *, session=None):
         """
         instantiate a Cone Search service
 
@@ -139,7 +139,7 @@ def columns(self):
         except AttributeError:
             return []
 
-    def search(self, pos, radius=1.0, verbosity=2, **keywords):
+    def search(self, pos, *, radius=1.0, verbosity=2, **keywords):
         """
         submit a simple Cone Search query that requests objects or observations
         whose positions fall within some distance from a search position.
@@ -186,7 +186,7 @@ def search(self, pos, radius=1.0, verbosity=2, **keywords):
         """
         return self.create_query(pos=pos, radius=radius, verbosity=verbosity, **keywords).execute()
 
-    def create_query(self, pos=None, radius=None, verbosity=None, **keywords):
+    def create_query(self, pos=None, *, radius=None, verbosity=None, **keywords):
         """
         create a query object that constraints can be added to and then
         executed.  The input arguments will initialize the query with the
@@ -275,7 +275,7 @@ class SCSQuery(DALQuery):
     """
 
     def __init__(
-            self, baseurl, pos=None, radius=None, verbosity=None, session=None, **keywords):
+            self, baseurl, pos=None, *, radius=None, verbosity=None, session=None, **keywords):
         """
         initialize the query object with a baseurl and the given parameters
 

pyvo/dal/sia.py

@@ -46,7 +46,7 @@
 
 
 def search(
-        url, pos, size=1.0, format=None, intersect=None, verbosity=2,
+        url, pos, *, size=1.0, format=None, intersect=None, verbosity=2,
         **keywords):
     """
     submit a simple SIA query that requests images overlapping a given region
@@ -122,7 +122,7 @@ class SIAService(DALService):
     a representation of an SIA service
     """
 
-    def __init__(self, baseurl, session=None):
+    def __init__(self, baseurl, *, session=None):
         """
         instantiate an SIA service
 
@@ -188,7 +188,7 @@ def columns(self):
             return []
 
     def search(
-            self, pos, size=1.0, format=None, intersect=None,
+            self, pos, *, size=1.0, format=None, intersect=None,
             verbosity=2, **keywords):
         """
         submit a SIA query to this service with the given parameters.
@@ -259,7 +259,7 @@ def search(
             pos=pos, size=size, format=format, intersect=intersect, verbosity=verbosity, **keywords).execute()
 
     def create_query(
-            self, pos=None, size=None, format=None, intersect=None,
+            self, pos=None, *, size=None, format=None, intersect=None,
             verbosity=None, **keywords):
         """
         create a query object that constraints can be added to and then
@@ -347,7 +347,7 @@ class SIAQuery(DALQuery):
     """
 
     def __init__(
-            self, baseurl, pos=None, size=None, format=None, intersect=None,
+            self, baseurl, pos=None, *, size=None, format=None, intersect=None,
             verbosity=None, session=None, **keywords):
         """
         initialize the query object with a baseurl and the given parameters
@@ -903,15 +903,15 @@ def suggest_dataset_basename(self):
             out = re.sub(r'\s+', '_', out.strip())
         return out
 
-    def suggest_extension(self, default=None):
+    def suggest_extension(self, *, default=None):
         """
         returns a recommended filename extension for the dataset described
         by this record.  Typically, this would look at the column describing
         the format and choose an extension accordingly.
         """
         return mime2extension(self.format, default)
 
-    def broadcast_samp(self, client_name=None):
+    def broadcast_samp(self, *, client_name=None):
         """
         Broadcast the image to ``client_name`` via SAMP
         """

pyvo/dal/sia2.py

@@ -102,7 +102,7 @@ def __getattr__(name):
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
 
-def search(url, pos=None, band=None, time=None, pol=None,
+def search(url, pos=None, *, band=None, time=None, pol=None,
            field_of_view=None, spatial_resolution=None,
            spectral_resolving_power=None, exptime=None,
            timeres=None, publisher_did=None, facility=None, collection=None,
@@ -156,7 +156,7 @@ class SIA2Service(DALService, AvailabilityMixin, CapabilityMixin):
     generally not notice that, though.
     """
 
-    def __init__(self, baseurl, session=None, check_baseurl=True):
+    def __init__(self, baseurl, *, session=None, check_baseurl=True):
         """
         instantiate an SIA2 service
 
@@ -198,7 +198,7 @@ def __init__(self, baseurl, session=None, check_baseurl=True):
                         continue
                     break
 
-    def search(self, pos=None, band=None, time=None, pol=None,
+    def search(self, pos=None, *, band=None, time=None, pol=None,
                field_of_view=None, spatial_resolution=None,
                spectral_resolving_power=None, exptime=None,
                timeres=None, publisher_did=None, facility=None, collection=None,
@@ -232,7 +232,7 @@ class SIA2Query(DALQuery, AxisParamMixin):
     used to interact with SIA2 services.
     """
 
-    def __init__(self, url, pos=None, band=None, time=None, pol=None,
+    def __init__(self, url, pos=None, *, band=None, time=None, pol=None,
                  field_of_view=None, spatial_resolution=None,
                  spectral_resolving_power=None, exptime=None,
                  timeres=None, publisher_did=None,

pyvo/dal/sla.py

@@ -71,7 +71,7 @@ class SLAService(DALService):
     """
     a representation of an spectral line catalog (SLA) service
     """
-    def __init__(self, baseurl, session=None):
+    def __init__(self, baseurl, *, session=None):
         """
         instantiate an SLA service
 
@@ -163,7 +163,7 @@ def search(self, wavelength, **keywords):
         """
         return self.create_query(wavelength, **keywords).execute()
 
-    def create_query(self, wavelength=None, request="queryData", **keywords):
+    def create_query(self, wavelength=None, *, request="queryData", **keywords):
         """
         create a query object that constraints can be added to and then
         executed.  The input arguments will initialize the query with the
@@ -242,8 +242,7 @@ class SLAQuery(DALQuery):
     """
 
     def __init__(
-            self, baseurl, wavelength=None, request="queryData", session=None,
-            **keywords):
+            self, baseurl, wavelength=None, *, request="queryData", session=None):
         """
         initialize the query object with a baseurl and the given parameters
 
@@ -256,11 +255,6 @@ def __init__(
             assuming meters if unit is not specified.
         session : object
            optional session to use for network requests
-        **keywords :
-            additional parameters can be given via arbitrary
-            case insensitive keyword arguments. Where there is overlap
-            with the parameters set by the other arguments to
-            this function, these keywords will override.
         """
         super().__init__(baseurl, session=session)