diff --git a/pandas/core/accessor.py b/pandas/core/accessor.py index 963c9c65cb30c..b95f60941dc28 100644 --- a/pandas/core/accessor.py +++ b/pandas/core/accessor.py @@ -35,7 +35,10 @@ def _dir_additions(self): def __dir__(self): """ - Provide method name lookup and completion + Provide method name lookup and completion. + + Notes + ----- Only provide 'public' methods. """ rv = set(dir(type(self))) @@ -45,7 +48,7 @@ def __dir__(self): class PandasDelegate: """ - An abstract base class for delegating methods/properties. + Abstract base class for delegating methods/properties. """ def _delegate_property_get(self, name, *args, **kwargs): @@ -66,12 +69,15 @@ def _add_delegate_accessors( Parameters ---------- - cls : the class to add the methods/properties to - delegate : the class to get methods/properties & doc-strings - accessors : string list of accessors to add - typ : 'property' or 'method' - overwrite : boolean, default False - Overwrite the method/property in the target class if it exists. + cls + Class to add the methods/properties to. + delegate + Class to get methods/properties and doc-strings. + accessors : list of str + List of accessors to add. + typ : {'property', 'method'} + overwrite : bool, default False + Overwrite the method/property in the target class if it exists. """ def _create_delegator_property(name): @@ -122,7 +128,7 @@ def delegate_names(delegate, accessors, typ: str, overwrite: bool = False): accessors : Sequence[str] List of accessor to add. typ : {'property', 'method'} - overwrite : boolean, default False + overwrite : bool, default False Overwrite the method/property in the target class if it exists. Returns @@ -152,16 +158,22 @@ def add_delegate_accessors(cls): class CachedAccessor: """ - Custom property-like object (descriptor) for caching accessors. + Custom property-like object. + + A descriptor for caching accessors. Parameters ---------- name : str - The namespace this will be accessed under, e.g. ``df.foo``. + Namespace that will be accessed under, e.g. ``df.foo``. accessor : cls - The class with the extension methods. The class' __init__ method - should expect one of a ``Series``, ``DataFrame`` or ``Index`` as - the single argument ``data``. + Class with the extension methods. + + Notes + ----- + For accessor, The class's __init__ method assumes that one of + ``Series``, ``DataFrame`` or ``Index`` as the + single argument ``data``. """ def __init__(self, name: str, accessor) -> None: diff --git a/pandas/core/sorting.py b/pandas/core/sorting.py index 3005bdcbe78a4..51c154aa47518 100644 --- a/pandas/core/sorting.py +++ b/pandas/core/sorting.py @@ -31,19 +31,24 @@ def get_group_index(labels, shape, sort: bool, xnull: bool): Parameters ---------- - labels: sequence of arrays + labels : sequence of arrays Integers identifying levels at each location - shape: sequence of ints same length as labels + shape : sequence of ints Number of unique levels at each location - sort: boolean + sort : bool If the ranks of returned ids should match lexical ranks of labels - xnull: boolean + xnull : bool If true nulls are excluded. i.e. -1 values in the labels are - passed through + passed through. + Returns ------- An array of type int64 where two elements are equal if their corresponding labels are equal at all location. + + Notes + ----- + The length of `labels` and `shape` must be identical. """ def _int64_cut_off(shape) -> int: @@ -104,7 +109,6 @@ def maybe_lift(lab, size): def get_compressed_ids(labels, sizes): """ - Group_index is offsets into cartesian product of all possible labels. This space can be huge, so this function compresses it, by computing offsets (comp_ids) into the list of unique labels (obs_group_ids). @@ -117,7 +121,6 @@ def get_compressed_ids(labels, sizes): Returns ------- tuple of (comp_ids, obs_group_ids) - """ ids = get_group_index(labels, sizes, sort=True, xnull=False) return compress_group_index(ids, sort=True) @@ -153,14 +156,13 @@ def decons_group_index(comp_labels, shape): def decons_obs_group_ids(comp_ids, obs_ids, shape, labels, xnull: bool): """ - reconstruct labels from observed group ids + Reconstruct labels from observed group ids. Parameters ---------- - xnull: boolean, - if nulls are excluded; i.e. -1 labels are passed through + xnull : bool + If nulls are excluded; i.e. -1 labels are passed through. """ - if not xnull: lift = np.fromiter(((a == -1).any() for a in labels), dtype="i8") shape = np.asarray(shape, dtype="i8") + lift @@ -188,6 +190,11 @@ def indexer_from_factorized(labels, shape, compress: bool = True): def lexsort_indexer(keys, orders=None, na_position: str = "last"): + """ + Parameters + ---------- + na_position : {'first', 'last'}, default 'last' + """ from pandas.core.arrays import Categorical labels = [] @@ -237,9 +244,17 @@ def nargsort( items, kind: str = "quicksort", ascending: bool = True, na_position: str = "last" ): """ - This is intended to be a drop-in replacement for np.argsort which - handles NaNs. It adds ascending and na_position parameters. - GH #6399, #5231 + Intended to be a drop-in replacement for np.argsort which handles NaNs. + + Adds ascending and na_position parameters. + + (GH #6399, #5231) + + Parameters + ---------- + kind : str, default 'quicksort' + ascending : bool, default True + na_position : {'first', 'last'}, default 'last' """ items = extract_array(items) mask = np.asarray(isna(items)) @@ -272,7 +287,7 @@ def nargsort( class _KeyMapper: """ - Ease my suffering. Map compressed group id -> key tuple + Map compressed group id -> key tuple. """ def __init__(self, comp_ids, ngroups: int, levels, labels): @@ -303,7 +318,12 @@ def get_flattened_iterator(comp_ids, ngroups, levels, labels): def get_indexer_dict(label_list, keys): - """ return a dict of {labels} -> {indexers} """ + """ + Returns + ------- + dict + Labels mapped to indexers. + """ shape = [len(x) for x in keys] group_index = get_group_index(label_list, shape, sort=True, xnull=True)