Repository: mie-lab/trackintel
Pull request #338 (2021-09-14 19:28:53)

CLN: Turn `copy_docstring` to a protected function.
This function isn't meant to be externally visible.
Also add a docstring describing the function a bit.

codecov[bot]: # [Codecov](https://codecov.io/gh/mie-lab/trackintel/pull/338?src=pr&el=h1&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=mie-lab) Report
> Merging [#338](https://codecov.io/gh/mie-lab/trackintel/pull/338?src=pr&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=mie-lab) (7668e51) into [master](https://codecov.io/gh/mie-lab/trackintel/commit/b89f0c8c35cc1adcc858a8bdc60a32d32b50a2b9?el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=mie-lab) (b89f0c8) will **decrease** coverage by `2.23%`.
> The diff coverage is `100.00%`.

[![Impacted file tree graph](https://codecov.io/gh/mie-lab/trackintel/pull/338/graphs/tree.svg?width=650&height=150&src=pr&token=ITDZEEE1MO&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=mie-lab)](https://codecov.io/gh/mie-lab/trackintel/pull/338?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=mie-lab)

```diff
@@            Coverage Diff             @@
##           master     #338      +/-   ##
==========================================
- Coverage   96.41%   94.17%   -2.24%     
==========================================
  Files          40       40              
  Lines        1924     1924              
  Branches      313      313              
==========================================
- Hits         1855     1812      -43     
- Misses         31       75      +44     
+ Partials       38       37       -1     
```


| [Impacted Files](https://codecov.io/gh/mie-lab/trackintel/pull/338?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=mie-lab) | Coverage Δ | |
|---|---|---|
| [trackintel/model/locations.py](https://codecov.io/gh/mie-lab/trackintel/pull/338/diff?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=mie-lab#diff-dHJhY2tpbnRlbC9tb2RlbC9sb2NhdGlvbnMucHk=) | `96.87% <100.00%> (-3.13%)` | :arrow_down: |
| [trackintel/model/positionfixes.py](https://codecov.io/gh/mie-lab/trackintel/pull/338/diff?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=mie-lab#diff-dHJhY2tpbnRlbC9tb2RlbC9wb3NpdGlvbmZpeGVzLnB5) | `97.82% <100.00%> (-2.18%)` | :arrow_down: |
| [trackintel/model/staypoints.py](https://codecov.io/gh/mie-lab/trackintel/pull/338/diff?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=mie-lab#diff-dHJhY2tpbnRlbC9tb2RlbC9zdGF5cG9pbnRzLnB5) | `98.14% <100.00%> (-1.86%)` | :arrow_down: |
| [trackintel/model/triplegs.py](https://codecov.io/gh/mie-lab/trackintel/pull/338/diff?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=mie-lab#diff-dHJhY2tpbnRlbC9tb2RlbC90cmlwbGVncy5weQ==) | `98.27% <100.00%> (-1.73%)` | :arrow_down: |
| [trackintel/model/trips.py](https://codecov.io/gh/mie-lab/trackintel/pull/338/diff?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=mie-lab#diff-dHJhY2tpbnRlbC9tb2RlbC90cmlwcy5weQ==) | `97.22% <100.00%> (-2.78%)` | :arrow_down: |
| [trackintel/model/util.py](https://codecov.io/gh/mie-lab/trackintel/pull/338/diff?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=mie-lab#diff-dHJhY2tpbnRlbC9tb2RlbC91dGlsLnB5) | `100.00% <100.00%> (ø)` | |
| [trackintel/io/postgis.py](https://codecov.io/gh/mie-lab/trackintel/pull/338/diff?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=mie-lab#diff-dHJhY2tpbnRlbC9pby9wb3N0Z2lzLnB5) | `49.36% <0.00%> (-48.11%)` | :arrow_down: |
| ... and [1 more](https://codecov.io/gh/mie-lab/trackintel/pull/338/diff?src=pr&el=tree-more&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=mie-lab) | |

------

[Continue to review full report at Codecov](https://codecov.io/gh/mie-lab/trackintel/pull/338?src=pr&el=continue&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=mie-lab).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=mie-lab)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/mie-lab/trackintel/pull/338?src=pr&el=footer&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=mie-lab). Last update [b89f0c8...7668e51](https://codecov.io/gh/mie-lab/trackintel/pull/338?src=pr&el=lastupdated&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=mie-lab). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=mie-lab).

hong2223: 👍 

Patch:
diff --git a/trackintel/model/locations.py b/trackintel/model/locations.py
index 74daac8..7d1e901 100644
--- a/trackintel/model/locations.py
+++ b/trackintel/model/locations.py
@@ -3,7 +3,7 @@ import trackintel as ti
 import trackintel.io
 from trackintel.io.file import write_locations_csv
 from trackintel.io.postgis import write_locations_postgis
-from trackintel.model.util import copy_docstring
+from trackintel.model.util import _copy_docstring
 from trackintel.preprocessing.filter import spatial_filter
 from trackintel.visualization.locations import plot_locations
 
@@ -50,7 +50,7 @@ class LocationsAccessor(object):
             # One for extend and one for the center
             raise AttributeError("The center geometry must be a Point (only first checked).")
 
-    @copy_docstring(plot_locations)
+    @_copy_docstring(plot_locations)
     def plot(self, *args, **kwargs):
         """
         Plot this collection of locations.
@@ -59,7 +59,7 @@ class LocationsAccessor(object):
         """
         ti.visualization.locations.plot_locations(self._obj, *args, **kwargs)
 
-    @copy_docstring(write_locations_csv)
+    @_copy_docstring(write_locations_csv)
     def to_csv(self, filename, *args, **kwargs):
         """
         Store this collection of locations as a CSV file.
@@ -68,7 +68,7 @@ class LocationsAccessor(object):
         """
         ti.io.file.write_locations_csv(self._obj, filename, *args, **kwargs)
 
-    @copy_docstring(write_locations_postgis)
+    @_copy_docstring(write_locations_postgis)
     def to_postgis(
         self, name, con, schema=None, if_exists="fail", index=True, index_label=None, chunksize=None, dtype=None
     ):
@@ -81,7 +81,7 @@ class LocationsAccessor(object):
             self._obj, name, con, schema, if_exists, index, index_label, chunksize, dtype
         )
 
-    @copy_docstring(spatial_filter)
+    @_copy_docstring(spatial_filter)
     def spatial_filter(self, *args, **kwargs):
         """
         Filter locations with a geo extent.
diff --git a/trackintel/model/positionfixes.py b/trackintel/model/positionfixes.py
index 5e037c9..937c086 100644
--- a/trackintel/model/positionfixes.py
+++ b/trackintel/model/positionfixes.py
@@ -3,7 +3,7 @@ import trackintel as ti
 from trackintel.geogr.distances import calculate_distance_matrix
 from trackintel.io.file import write_positionfixes_csv
 from trackintel.io.postgis import write_positionfixes_postgis
-from trackintel.model.util import copy_docstring
+from trackintel.model.util import _copy_docstring
 from trackintel.preprocessing.positionfixes import generate_staypoints, generate_triplegs
 from trackintel.visualization.positionfixes import plot_positionfixes
 
@@ -73,7 +73,7 @@ class PositionfixesAccessor(object):
         lon = self._obj.geometry.x
         return (float(lon.mean()), float(lat.mean()))
 
-    @copy_docstring(generate_staypoints)
+    @_copy_docstring(generate_staypoints)
     def generate_staypoints(self, *args, **kwargs):
         """
         Generate staypoints from this collection of positionfixes.
@@ -82,7 +82,7 @@ class PositionfixesAccessor(object):
         """
         return ti.preprocessing.positionfixes.generate_staypoints(self._obj, *args, **kwargs)
 
-    @copy_docstring(generate_triplegs)
+    @_copy_docstring(generate_triplegs)
     def generate_triplegs(self, staypoints=None, *args, **kwargs):
         """
         Generate triplegs from this collection of positionfixes.
@@ -91,7 +91,7 @@ class PositionfixesAccessor(object):
         """
         return ti.preprocessing.positionfixes.generate_triplegs(self._obj, staypoints, *args, **kwargs)
 
-    @copy_docstring(plot_positionfixes)
+    @_copy_docstring(plot_positionfixes)
     def plot(self, *args, **kwargs):
         """
         Plot this collection of positionfixes.
@@ -100,7 +100,7 @@ class PositionfixesAccessor(object):
         """
         ti.visualization.positionfixes.plot_positionfixes(self._obj, *args, **kwargs)
 
-    @copy_docstring(write_positionfixes_csv)
+    @_copy_docstring(write_positionfixes_csv)
     def to_csv(self, filename, *args, **kwargs):
         """
         Store this collection of trackpoints as a CSV file.
@@ -109,7 +109,7 @@ class PositionfixesAccessor(object):
         """
         ti.io.file.write_positionfixes_csv(self._obj, filename, *args, **kwargs)
 
-    @copy_docstring(write_positionfixes_postgis)
+    @_copy_docstring(write_positionfixes_postgis)
     def to_postgis(
         self, name, con, schema=None, if_exists="fail", index=True, index_label=None, chunksize=None, dtype=None
     ):
@@ -122,7 +122,7 @@ class PositionfixesAccessor(object):
             self._obj, name, con, schema, if_exists, index, index_label, chunksize, dtype
         )
 
-    @copy_docstring(calculate_distance_matrix)
+    @_copy_docstring(calculate_distance_matrix)
     def calculate_distance_matrix(self, *args, **kwargs):
         """
         Calculate pair-wise distance among positionfixes or to other positionfixes.
diff --git a/trackintel/model/staypoints.py b/trackintel/model/staypoints.py
index 6586e46..1069944 100644
--- a/trackintel/model/staypoints.py
+++ b/trackintel/model/staypoints.py
@@ -4,7 +4,7 @@ from trackintel.analysis.labelling import create_activity_flag
 from trackintel.analysis.tracking_quality import temporal_tracking_quality
 from trackintel.io.file import write_staypoints_csv
 from trackintel.io.postgis import write_staypoints_postgis
-from trackintel.model.util import copy_docstring
+from trackintel.model.util import _copy_docstring
 from trackintel.preprocessing.filter import spatial_filter
 from trackintel.preprocessing.staypoints import generate_locations, merge_staypoints
 from trackintel.visualization.staypoints import plot_staypoints
@@ -78,7 +78,7 @@ class StaypointsAccessor(object):
         lon = self._obj.geometry.x
         return (float(lon.mean()), float(lat.mean()))
 
-    @copy_docstring(generate_locations)
+    @_copy_docstring(generate_locations)
     def generate_locations(self, *args, **kwargs):
         """
         Generate locations from this collection of staypoints.
@@ -87,7 +87,7 @@ class StaypointsAccessor(object):
         """
         return ti.preprocessing.staypoints.generate_locations(self._obj, *args, **kwargs)
 
-    @copy_docstring(merge_staypoints)
+    @_copy_docstring(merge_staypoints)
     def merge_staypoints(self, *args, **kwargs):
         """
         Aggregate staypoints horizontally via time threshold.
@@ -96,7 +96,7 @@ class StaypointsAccessor(object):
         """
         return ti.preprocessing.staypoints.merge_staypoints(self._obj, *args, **kwargs)
 
-    @copy_docstring(create_activity_flag)
+    @_copy_docstring(create_activity_flag)
     def create_activity_flag(self, *args, **kwargs):
         """
         Set a flag if a staypoint is also an activity.
@@ -105,7 +105,7 @@ class StaypointsAccessor(object):
         """
         return ti.analysis.labelling.create_activity_flag(self._obj, *args, **kwargs)
 
-    @copy_docstring(spatial_filter)
+    @_copy_docstring(spatial_filter)
     def spatial_filter(self, *args, **kwargs):
         """
         Filter staypoints with a geo extent.
@@ -114,7 +114,7 @@ class StaypointsAccessor(object):
         """
         return ti.preprocessing.filter.spatial_filter(self._obj, *args, **kwargs)
 
-    @copy_docstring(plot_staypoints)
+    @_copy_docstring(plot_staypoints)
     def plot(self, *args, **kwargs):
         """
         Plot this collection of staypoints.
@@ -123,7 +123,7 @@ class StaypointsAccessor(object):
         """
         ti.visualization.staypoints.plot_staypoints(self._obj, *args, **kwargs)
 
-    @copy_docstring(write_staypoints_csv)
+    @_copy_docstring(write_staypoints_csv)
     def to_csv(self, filename, *args, **kwargs):
         """
         Store this collection of staypoints as a CSV file.
@@ -132,7 +132,7 @@ class StaypointsAccessor(object):
         """
         ti.io.file.write_staypoints_csv(self._obj, filename, *args, **kwargs)
 
-    @copy_docstring(write_staypoints_postgis)
+    @_copy_docstring(write_staypoints_postgis)
     def to_postgis(
         self, name, con, schema=None, if_exists="fail", index=True, index_label=None, chunksize=None, dtype=None
     ):
@@ -145,7 +145,7 @@ class StaypointsAccessor(object):
             self._obj, name, con, schema, if_exists, index, index_label, chunksize, dtype
         )
 
-    @copy_docstring(temporal_tracking_quality)
+    @_copy_docstring(temporal_tracking_quality)
     def temporal_tracking_quality(self, *args, **kwargs):
         """
         Calculate per-user temporal tracking quality (temporal coverage).
diff --git a/trackintel/model/triplegs.py b/trackintel/model/triplegs.py
index 0f4011b..7e72c3e 100644
--- a/trackintel/model/triplegs.py
+++ b/trackintel/model/triplegs.py
@@ -7,7 +7,7 @@ from trackintel.analysis.tracking_quality import temporal_tracking_quality
 from trackintel.geogr.distances import calculate_distance_matrix
 from trackintel.io.file import write_triplegs_csv
 from trackintel.io.postgis import write_triplegs_postgis
-from trackintel.model.util import copy_docstring
+from trackintel.model.util import _copy_docstring
 from trackintel.preprocessing.filter import spatial_filter
 from trackintel.preprocessing.triplegs import generate_trips
 from trackintel.visualization.triplegs import plot_triplegs
@@ -71,7 +71,7 @@ class TriplegsAccessor(object):
             obj["finished_at"]
         ), "dtype of finished_at is {} but has to be datetime64 and timezone aware".format(obj["finished_at"].dtype)
 
-    @copy_docstring(plot_triplegs)
+    @_copy_docstring(plot_triplegs)
     def plot(self, *args, **kwargs):
         """
         Plot this collection of triplegs.
@@ -80,7 +80,7 @@ class TriplegsAccessor(object):
         """
         ti.visualization.triplegs.plot_triplegs(self._obj, *args, **kwargs)
 
-    @copy_docstring(write_triplegs_csv)
+    @_copy_docstring(write_triplegs_csv)
     def to_csv(self, filename, *args, **kwargs):
         """
         Store this collection of triplegs as a CSV file.
@@ -89,7 +89,7 @@ class TriplegsAccessor(object):
         """
         ti.io.file.write_triplegs_csv(self._obj, filename, *args, **kwargs)
 
-    @copy_docstring(write_triplegs_postgis)
+    @_copy_docstring(write_triplegs_postgis)
     def to_postgis(
         self, name, con, schema=None, if_exists="fail", index=True, index_label=None, chunksize=None, dtype=None
     ):
@@ -102,7 +102,7 @@ class TriplegsAccessor(object):
             self._obj, name, con, schema, if_exists, index, index_label, chunksize, dtype
         )
 
-    @copy_docstring(calculate_distance_matrix)
+    @_copy_docstring(calculate_distance_matrix)
     def calculate_distance_matrix(self, *args, **kwargs):
         """
         Calculate pair-wise distance among triplegs or to other triplegs.
@@ -111,7 +111,7 @@ class TriplegsAccessor(object):
         """
         return ti.geogr.distances.calculate_distance_matrix(self._obj, *args, **kwargs)
 
-    @copy_docstring(spatial_filter)
+    @_copy_docstring(spatial_filter)
     def spatial_filter(self, *args, **kwargs):
         """
         Filter triplegs with a geo extent.
@@ -120,7 +120,7 @@ class TriplegsAccessor(object):
         """
         return ti.preprocessing.filter.spatial_filter(self._obj, *args, **kwargs)
 
-    @copy_docstring(generate_trips)
+    @_copy_docstring(generate_trips)
     def generate_trips(self, *args, **kwargs):
         """
         Generate trips based on staypoints and triplegs.
@@ -138,7 +138,7 @@ class TriplegsAccessor(object):
             )
             return ti.preprocessing.triplegs.generate_trips(staypoints=args[0], triplegs=self._obj, **kwargs)
 
-    @copy_docstring(predict_transport_mode)
+    @_copy_docstring(predict_transport_mode)
     def predict_transport_mode(self, *args, **kwargs):
         """
         Predict/impute the transport mode with which each tripleg was likely covered.
@@ -147,7 +147,7 @@ class TriplegsAccessor(object):
         """
         return ti.analysis.labelling.predict_transport_mode(self._obj, *args, **kwargs)
 
-    @copy_docstring(calculate_modal_split)
+    @_copy_docstring(calculate_modal_split)
     def calculate_modal_split(self, *args, **kwargs):
         """
         Calculate the modal split of the triplegs.
@@ -156,7 +156,7 @@ class TriplegsAccessor(object):
         """
         return ti.analysis.modal_split.calculate_modal_split(self._obj, *args, **kwargs)
 
-    @copy_docstring(temporal_tracking_quality)
+    @_copy_docstring(temporal_tracking_quality)
     def temporal_tracking_quality(self, *args, **kwargs):
         """
         Calculate per-user temporal tracking quality (temporal coverage).
diff --git a/trackintel/model/trips.py b/trackintel/model/trips.py
index 6b35fde..234b358 100644
--- a/trackintel/model/trips.py
+++ b/trackintel/model/trips.py
@@ -1,7 +1,7 @@
 from trackintel.analysis.tracking_quality import temporal_tracking_quality
 from trackintel.io.postgis import write_trips_postgis
 from trackintel.io.file import write_trips_csv
-from trackintel.model.util import copy_docstring
+from trackintel.model.util import _copy_docstring
 import pandas as pd
 import geopandas as gpd
 
@@ -83,7 +83,7 @@ class TripsAccessor(object):
         """
         raise NotImplementedError
 
-    @copy_docstring(write_trips_csv)
+    @_copy_docstring(write_trips_csv)
     def to_csv(self, filename, *args, **kwargs):
         """
         Store this collection of trips as a CSV file.
@@ -92,7 +92,7 @@ class TripsAccessor(object):
         """
         ti.io.file.write_trips_csv(self._obj, filename, *args, **kwargs)
 
-    @copy_docstring(write_trips_postgis)
+    @_copy_docstring(write_trips_postgis)
     def to_postgis(
         self, name, con, schema=None, if_exists="fail", index=True, index_label=None, chunksize=None, dtype=None
     ):
@@ -103,7 +103,7 @@ class TripsAccessor(object):
         """
         ti.io.postgis.write_trips_postgis(self._obj, name, con, schema, if_exists, index, index_label, chunksize, dtype)
 
-    @copy_docstring(temporal_tracking_quality)
+    @_copy_docstring(temporal_tracking_quality)
     def temporal_tracking_quality(self, *args, **kwargs):
         """
         Calculate per-user temporal tracking quality (temporal coverage).
diff --git a/trackintel/model/util.py b/trackintel/model/util.py
index 1dc9cd1..91de030 100644
--- a/trackintel/model/util.py
+++ b/trackintel/model/util.py
@@ -1,5 +1,6 @@
 from functools import partial, update_wrapper
 
 
-def copy_docstring(wrapped, assigned=("__doc__",), updated=[]):
+def _copy_docstring(wrapped, assigned=("__doc__",), updated=[]):
+    """Thin wrapper for `functools.update_wrapper` to mimic `functools.wraps` but to only copy the docstring."""
     return partial(update_wrapper, wrapped=wrapped, assigned=assigned, updated=updated)


Test patch:
diff --git a/tests/model/test_util.py b/tests/model/test_util.py
index bb4db52..5856312 100644
--- a/tests/model/test_util.py
+++ b/tests/model/test_util.py
@@ -1,11 +1,11 @@
-from trackintel.model.util import copy_docstring
+from trackintel.model.util import _copy_docstring
 from functools import WRAPPER_ASSIGNMENTS
 from trackintel.io.postgis import read_trips_postgis
 
 
-class TestCopy_Docstring:
+class Test_copy_docstring:
     def test_default(self):
-        @copy_docstring(read_trips_postgis)
+        @_copy_docstring(read_trips_postgis)
         def bar(b: int) -> int:
             """Old docstring."""
             pass