Skip to content

Commit

Permalink
docs: fix doctring style
Browse files Browse the repository at this point in the history 
did a pass of ruff's doctrings linter
  • Loading branch information
@ManonMarchand
ManonMarchand committed Apr 22, 2024
1 parent 5e177dd commit 815c6bf
Show file tree
Hide file tree
Showing 3 changed files with 83 additions and 61 deletions.
102 changes: 62 additions & 40 deletions src/ipyaladin/__init__.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,13 +34,14 @@ class Aladin(anywidget.AnyWidget):
height = Int(400).tag(sync=True, init_option=True)
_target = Unicode(
"0 0",
help="this trait is used belong the target property "
"to store the current target of Aladin Lite",
help="A private trait that stores the current target of the widget in a string."
" Its public version is the 'target' property that returns an "
"`~astropy.coordinates.SkyCoord` object",
).tag(sync=True, init_option=True)
shared_target = Unicode(
"0 0",
help="this trait is destined to be used with jslink widget function "
"to link two Aladin Lite widgets target together",
help="A trait that can be used with `~ipywidgets.widgets.jslink`"
"to link two Aladin Lite widgets targets together",
).tag(sync=True)
fov = Float(60.0).tag(sync=True, init_option=True)
survey = Unicode("https://alaskybis.unistra.fr/DSS/DSSColor").tag(
Expand Down Expand Up @@ -120,13 +121,15 @@ def _handle_custom_message(self, model, message, list_of_buffers): # noqa: ARG0

@property
def target(self) -> SkyCoord:
"""
Get the target of the Aladin Lite widget.
"""The target of the Aladin Lite widget.
It can be set with either a string of an `~astropy.coordinates.SkyCoord` object.
Returns
-------
SkyCoord
An astropy.coordinates.SkyCoord object representing the target.
"""
ra, dec = self._target.split(" ")
return SkyCoord(
Expand All @@ -138,19 +141,6 @@ def target(self) -> SkyCoord:

@target.setter
def target(self, target: Union[str, SkyCoord]):
"""
Set the target of the Aladin Lite widget.
Parameters
----------
target : str or SkyCoord
The target as either a string or an astropy.coordinates.SkyCoord object.
Raises
------
ValueError
If the target is not a string or an astropy.coordinates.SkyCoord object.
"""
if isinstance(target, str): # If the target is str, parse it
target = parse_coordinate_string(target)
elif not isinstance(target, SkyCoord): # If the target is not str or SkyCoord
Expand All @@ -167,10 +157,14 @@ def target(self, target: Union[str, SkyCoord]):
)

def add_catalog_from_URL(self, votable_URL, votable_options=None):
"""load a VOTable table from an url and load its data into the widget
Args:
votable_URL: string url
votable_options: dictionary object"""
"""Load a VOTable table from an url and load its data into the widget.
Parameters
----------
votable_URL: str
votable_options: dict
"""
if votable_options is None:
votable_options = {}
self.send(
Expand All @@ -184,6 +178,17 @@ def add_catalog_from_URL(self, votable_URL, votable_options=None):
# MOCs

def add_moc(self, moc, **moc_options):
"""Add a MOC to the Aladin-Lite widget.
Parameters
----------
moc : `~mocpy.MOC` or str or dict
The MOC can be provided as a `mocpy.MOC` object, as a string containing an
URL where the MOC can be retrieved, or as a dictionary where the keys are
the HEALPix orders and the values are the pixel indices
(ex: {"1":[1,2,4], "2":[12,13,14,21,23,25]}).
"""
if isinstance(moc, dict):
self.send(
{
Expand Down Expand Up @@ -220,10 +225,15 @@ def add_moc(self, moc, **moc_options):
) from imp

def add_moc_from_URL(self, moc_URL, moc_options=None):
"""load a MOC from a URL and display it in Aladin Lite widget
Arguments:
moc_URL: string url
moc_options: dictionary object"""
"""Load a MOC from a URL and display it in Aladin Lite widget.
Parameters
----------
moc_URL: str
An URL to retrieve the MOC from
moc_options: dict
"""
warnings.warn(
"add_moc_from_URL is replaced by add_moc that detects automatically"
"that the MOC was given as an URL.",
Expand All @@ -235,12 +245,16 @@ def add_moc_from_URL(self, moc_URL, moc_options=None):
self.add_moc(moc_URL, **moc_options)

def add_moc_from_dict(self, moc_dict, moc_options=None):
"""load a MOC from a dict object and display it in Aladin Lite widget
Arguments:
moc_dict: the dict containing the MOC cells. Key are the HEALPix orders,
values are the pixel indexes,
eg: {"1":[1,2,4], "2":[12,13,14,21,23,25]}
moc_options: dictionary object"""
"""Load a MOC from a dict object and display it in Aladin Lite widget.
Parameters
----------
moc_dict: dict
It contains the MOC cells. Key are the HEALPix orders, values are the pixel
indexes, eg: {"1":[1,2,4], "2":[12,13,14,21,23,25]}
moc_options: dict
"""
warnings.warn(
"add_moc_from_dict is replaced by add_moc that detects automatically"
"that the MOC was given as a dictionary.",
Expand Down Expand Up @@ -278,8 +292,8 @@ def add_table(self, table, **table_options):
meta={"name": "my sample table"})
>>> aladin.add_table(table)
And the table should appear in the output of Cell 1!
"""
"""
# this library must be installed, and is used in votable operations
# http://www.astropy.org/
import io
Expand All @@ -295,9 +309,10 @@ def add_overlay_from_stcs(self, stc_string, **overlay_options):
Parameters
----------
stc_string: str
The STC-S string.
The STC-S string.
overlay_options: keyword arguments
TODO: documentation"""
"""
self.send(
{
"event_name": "add_overlay_from_stcs",
Expand All @@ -322,10 +337,17 @@ def rectangular_selection(self):
# Adding a listener

def add_listener(self, listener_type, callback):
"""add a listener to the widget
Args:
listener_type: string that can either be 'objectHovered' or 'objClicked'
callback: python function"""
"""Add a listener to the widget.
Parameters
----------
listener_type: str
Can either be 'objectHovered' or 'objClicked'
callback: Callable
A python function to be called when the event corresponding to the
listener_type is detected
"""
if listener_type in {"objectHovered", "object_hovered"}:
self.listener_callback["object_hovered"] = callback
elif listener_type in {"objectClicked", "object_clicked"}:
Expand Down
18 changes: 9 additions & 9 deletions src/ipyaladin/coordinate_parser.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,7 @@


def parse_coordinate_string(string: str) -> SkyCoord:
"""
Parse a string containing coordinates.
"""Parse a string containing coordinates.
Parameters
----------
Expand All @@ -14,7 +13,8 @@ def parse_coordinate_string(string: str) -> SkyCoord:
Returns
-------
SkyCoord
A SkyCoord object representing the coordinates.
An `astropy.coordinates.SkyCoord` object representing the coordinates.
"""
if not _is_coordinate_string(string):
return SkyCoord.from_name(string)
Expand All @@ -34,8 +34,7 @@ def parse_coordinate_string(string: str) -> SkyCoord:


def _is_coordinate_string(string: str) -> bool:
"""
Check if a string is a coordinate string.
"""Check if a string is a coordinate string.
Parameters
----------
Expand All @@ -46,14 +45,14 @@ def _is_coordinate_string(string: str) -> bool:
-------
bool
True if the string is a coordinate string, False otherwise.
"""
regex = r"^([JGB].*|[0-9][0-9: hmsd.°′'\"+-]+)$" # noqa RUF001
return bool(re.match(regex, string))


def _split_coordinate_string(coo: str) -> tuple[str, str]:
"""
Split a string containing coordinates in two parts.
"""Split a string containing coordinates in two parts.
Parameters
----------
Expand All @@ -64,6 +63,7 @@ def _split_coordinate_string(coo: str) -> tuple[str, str]:
-------
tuple[str, str]
A tuple containing the two parts of the coordinate as strings.
"""
# Remove first char if it is J, G or B
jgb_regex = r"^[JGB].*"
Expand All @@ -80,8 +80,7 @@ def _split_coordinate_string(coo: str) -> tuple[str, str]:


def _is_hour_angle_string(coo: str) -> bool:
"""
Check if a string is an hour angle string.
"""Check if a string is an hour angle string.
Parameters
----------
Expand All @@ -92,6 +91,7 @@ def _is_hour_angle_string(coo: str) -> bool:
-------
bool
True if the string is an hour angle string, False otherwise.
"""
regex = r"[hms°: ]"
return bool(re.search(regex, coo))
24 changes: 12 additions & 12 deletions src/test/test_coordinate_parser.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,15 +34,15 @@

@pytest.mark.parametrize(("inp", "expected"), test_is_coordinate_string_values)
def test_is_coordinate_string(inp, expected):
"""
Test the function _is_coordinate_string
"""Test the function _is_coordinate_string.
Parameters
----------
inp : str
A string with an object name or coordinates to check.
expected : bool
The expected result as a boolean.
"""
assert _is_coordinate_string(inp) == expected

Expand All @@ -69,15 +69,15 @@ def test_is_coordinate_string(inp, expected):

@pytest.mark.parametrize(("inp", "expected"), test_split_coordinate_string_values)
def test_split_coordinate_string(inp, expected):
"""
Test the function _split_coordinate_string
"""Test the function _split_coordinate_string.
Parameters
----------
inp : str
A string with coordinates to split.
expected : tuple of str
The expected result as a tuple of strings.
"""
assert _split_coordinate_string(inp) == expected

Expand All @@ -93,15 +93,15 @@ def test_split_coordinate_string(inp, expected):

@pytest.mark.parametrize(("inp", "expected"), test_is_hour_angle_string_values)
def test_is_hour_angle_string(inp, expected):
"""
Test the function _is_hour_angle_string
"""Test the function _is_hour_angle_string.
Parameters
----------
inp : str
A coordinate part as a string.
expected : bool
The expected result as a boolean.
"""
assert _is_hour_angle_string(inp) == expected

Expand Down Expand Up @@ -177,15 +177,15 @@ def test_is_hour_angle_string(inp, expected):

@pytest.mark.parametrize(("inp", "expected"), test_parse_coordinate_string_values)
def test_parse_coordinate_string(inp, expected):
"""
Test the function parse_coordinate_string
"""Test the function parse_coordinate_string.
Parameters
----------
inp : str
The string to parse.
expected : SkyCoord
The expected result as a SkyCoord object.
"""
assert parse_coordinate_string(inp) == expected

Expand Down Expand Up @@ -222,13 +222,13 @@ def test_parse_coordinate_string(inp, expected):

@pytest.mark.parametrize("target", test_aladin_string_target)
def test_aladin_string_target_set(target):
"""
Test setting the target of an Aladin object with a string or a SkyCoord object
"""Test setting the target of an Aladin object with a string or a SkyCoord object.
Parameters
----------
target : str
The target string.
"""
aladin = Aladin()
aladin.target = target
Expand All @@ -239,13 +239,13 @@ def test_aladin_string_target_set(target):

@pytest.mark.parametrize("target", test_aladin_string_target)
def test_aladin_sky_coord_target_set(target):
"""
Test setting and getting the target of an Aladin object with a SkyCoord object
"""Test setting and getting the target of an Aladin object with a SkyCoord object.
Parameters
----------
target : str
The target string.
"""
sc_target = parse_coordinate_string(target)
aladin = Aladin()
Expand Down

0 comments on commit 815c6bf

Please sign in to comment.