Skip to content

Functions#

At this point you have probably seen quite a few examples of functions that use pysmo types in this documentation. This chapter shows how to use pysmo types for the type hints in your functions.

Pysmo types as input#

The simplest way of using pysmo types is in functions that only use them as inputs. In these instances we don't need to be concerned about differences between different compatible classes, as their "journeys" end here. For example, the following function takes any Seismogram compatible object as input, and always returns a float regardless of what is used as input (e.g. MiniSeismogram, SacSeismogram, or a custom class):

double_delta_float.py
from pysmo import Seismogram
from datetime import timedelta


def double_delta_float(seismogram: Seismogram) -> timedelta:
    """Return double the sampling interval of a seismogram.

    Parameters:
        seismogram: Seismogram object.

    Returns:
        sampling interval multiplied by 2.
    """

    return seismogram.delta * 2

Because the function output is always a float, we don't lose track of any typing information when the function output is used elsewhere (e.g. in a function that needs a float as input).

Warning

Be careful when changing attributes of the input class inside a function. Sometimes the attributes are objects that contain other objects (e.g. an ndarray containing float objects). In our example above, the seismogram we use as input shares the nested objects in the data attribute with the seismogram inside the function. Changing seismgram.data inside the function will therefore also change it outside too. This behavior is often desired, but you must be aware of when this occurs and when not.

Mini classes as output#

While it may be perfectly acceptable to use pysmo types as output, we often lose some typing information when doing so. If we modify the above function to use a Seismogram for both input and output, we end up not knowing what exactly was used as input:

double_delta.py
from pysmo import Seismogram
from pysmo.classes import SAC
from copy import deepcopy
from typing import reveal_type  # (1)!


def double_delta(seismogram: Seismogram) -> Seismogram:
    """Double the sampling interval of a seismogram.

    Parameters:
        seismogram: Seismogram object.

    Returns:
        Seismogram with double the sampling interval of input seismogram.
    """

    clone = deepcopy(seismogram)  # (2)!
    clone.delta *= 2
    return clone


my_seis_in = SAC.from_file("testfile.sac").seismogram
my_seis_out = double_delta(my_seis_in)

reveal_type(my_seis_in)
reveal_type(my_seis_out)
  1. reveal_type allows us to inspect the actual type of an object. It prints type information at runtime (what it actually is) or when using mypy (what can be inferred from type annotations).
  2. 💡 Deep copying objects can be expensive if they contain large nested items.

The highlighted lines in the code above produce the following output when the script is executed:

python double_delta.pyRuntime type is 'SacSeismogram'
Runtime type is 'SacSeismogram'

This tells us that at runtime my_seis_in and my_seis_out are both of type SacSeismogram. Running mypy on the code, however, yields a different type for my_seis_out:

mypy double_delta.pydocs/snippets/double_delta.py:26: note: Revealed type is "SacSeismogram"
docs/snippets/double_delta.py:27: note: Revealed type is "Seismogram"
Success: no issues found in 1 source file

This discrepancy is due the fact that our function is annotated in a way that tells us any Seismogram is acceptable as input, and that a Seismogram is returned, but we don't know which type exactly that is going to be.

Tip

A modern editor may display type information without running mypy:

reveal type reveal type

This loss of information is often not a problem, but if you do intend to use the output of such a function for further processing, it might be better to be explicit about they type of output. Since all pysmo types have a corresponding Mini class, one strategy is to use those as output types:

double_delta_mini.py
from pysmo import Seismogram, MiniSeismogram
from pysmo.functions import clone_to_mini


def double_delta_mini(seismogram: Seismogram) -> MiniSeismogram:
    """Double the sampling interval of a seismogram.

    Parameters:
        seismogram: Seismogram object.

    Returns:
        MiniSeismogram with double the sampling interval of input seismogram.
    """

    clone = clone_to_mini(MiniSeismogram, seismogram)  # (1)!
    clone.delta *= 2
    return clone
  1. Here we use the clone_to_mini function to create a MiniSeismogram instances from other Seismogram instances. It is typically faster than deep copying because it only copies the attributes that are actually used.

Type preservation#

Another option to be explicit about the output type of a function is to declare that the input type has to be the same as the output type. For pysmo types this requires two things:

  1. We need to save the input type as variable which we can reference for the output type.
  2. We need to place bounds on this variable so that it is limited to the desired pysmo type(s).

This typing strategy involves generics, and changes our function to the following:

double_delta_generic.py
from pysmo import Seismogram
from pysmo.classes import SAC
from copy import deepcopy
from typing import reveal_type


def double_delta_generic[T: Seismogram](seismogram: T) -> T:  # (1)!
    """Double the sampling interval of a seismogram.

    Parameters:
        seismogram: Seismogram object.

    Returns:
        Seismogram with double the sampling interval of input seismogram.
    """

    clone = deepcopy(seismogram)
    clone.delta *= 2
    return clone


my_seis_in = SAC.from_file("testfile.sac").seismogram
my_seis_out = double_delta_generic(my_seis_in)

reveal_type(my_seis_in)
reveal_type(my_seis_out)
  1. 💡 This syntax is only valid for Python versions 3.12 and above.

In our example [T: Seismogram] defines a type variable T that has to be a Seismogram. We then use T as before to annotate the function. This means that if we use it with e.g. a MiniSeismogram as input, T is set to MiniSeismogram and the function signature effectively becomes:

def double_delta_generic(seismogram: MiniSeismogram) -> MiniSeismogram:
  ...

Or if we use a SacSeismogram:

def double_delta_generic(seismogram: SacSeismogram) -> SacSeismogram:
  ...

which is also what we used for our example. Therefore, running mypy on double_delta_generic.py gives:

mypy double_delta_generic.pydouble_delta_generic.py:25: note: Revealed type is "SacSeismogram"
double_delta_generic.py:26: note: Revealed type is "SacSeismogram"
Success: no issues found in 1 source file

Crucially, because T has an upper bound (in this case Seismogram), we get all the usual benefits from type hints while coding (autocompletion, error checking, etc.).