Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Rework docstrings to the Sphinx style #458

Merged
merged 1 commit into from
Jan 13, 2023
+170 −183
Merged

Rework docstrings to the Sphinx style #458

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 28 additions & 25 deletions mcstatus/address.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,12 +44,15 @@ class _AddressBase(NamedTuple):


class Address(_AddressBase):
"""Extension of a NamedTuple of host and port, for storing addresses.
"""Extension of a :class:`~typing.NamedTuple` of :attr:`.host` and :attr:`.port`, for storing addresses.

This class inherits from tuple, and is fully compatible with all functions
which require pure (host, port) address tuples, but on top of that, it includes
This class inherits from :class:`tuple`, and is fully compatible with all functions
which require pure ``(host, port)`` address tuples, but on top of that, it includes
some neat functionalities, such as validity ensuring, alternative constructors
for easy quick creation and methods handling IP resolving.

.. note::
Only attributes :attr:`host` and :attr:`port` are a part of Public API in this class.
"""

def __init__(self, *a, **kw):
Expand All @@ -71,28 +74,28 @@ def _ensure_validity(host: object, port: object) -> None:

@classmethod
def from_tuple(cls, tup: tuple[str, int]) -> Self:
"""Construct the class from a regular tuple of (host, port), commonly used for addresses."""
"""Construct the class from a regular tuple of ``(host, port)``, commonly used for addresses."""
return cls(host=tup[0], port=tup[1])

@classmethod
def from_path(cls, path: Path, *, default_port: int | None = None) -> Self:
"""Construct the class from a Path object.
"""Construct the class from a :class:`~pathlib.Path` object.

If path has a port specified, use it, if not fall back to default_port.
In case default_port isn't available and port wasn't specified, raise ValueError.
If path has a port specified, use it, if not fall back to ``default_port`` kwarg.
In case ``default_port`` isn't provided and port wasn't specified, raise :exc:`ValueError`.
"""
address = str(path)
return cls.parse_address(address, default_port=default_port)

@classmethod
def parse_address(cls, address: str, *, default_port: int | None = None) -> Self:
"""Parses a string address like 127.0.0.1:25565 into host and port parts
"""Parses a string address like ``127.0.0.1:25565`` into :attr:`.host` and :attr:`.port` parts.

If the address has a port specified, use it, if not, fall back to default_port.
If the address has a port specified, use it, if not, fall back to ``default_port`` kwarg.

:raises ValueError:
Either the address isn't valid and can't be parsed,
or it lacks a port and `default_port` wasn't specified.
or it lacks a port and ``default_port`` wasn't specified.
"""
hostname, port = _valid_urlparse(address)
if port is None:
Expand All @@ -112,10 +115,10 @@ def resolve_ip(self, lifetime: float | None = None) -> ipaddress.IPv4Address | i

:param lifetime:
How many seconds a query should run before timing out.
Default value for this is inherited from dns.resolver.resolve
Default value for this is inherited from :func:`dns.resolver.resolve`.
:raises dns.exception.DNSException:
One of the exceptions possibly raised by dns.resolver.resolve
Most notably this will be `dns.exception.Timeout` and `dns.resolver.NXDOMAIN`
One of the exceptions possibly raised by :func:`dns.resolver.resolve`.
Most notably this will be :exc:`dns.exception.Timeout` and :exc:`dns.resolver.NXDOMAIN`
"""
if self._cached_ip is not None:
return self._cached_ip
Expand All @@ -135,7 +138,7 @@ def resolve_ip(self, lifetime: float | None = None) -> ipaddress.IPv4Address | i
async def async_resolve_ip(self, lifetime: float | None = None) -> ipaddress.IPv4Address | ipaddress.IPv6Address:
"""Resolves a hostname's A record into an IP address.

See the docstring for `resolve_ip` for further info. This function is purely
See the docstring for :meth:`.resolve_ip` for further info. This function is purely
an async alternative to it.
"""
if self._cached_ip is not None:
Expand All @@ -160,22 +163,25 @@ def minecraft_srv_address_lookup(
default_port: int | None = None,
lifetime: float | None = None,
) -> Address:
"""Parses the address, if it doesn't include port, tries SRV record, if it's not there, falls back on default_port
"""Lookup the SRV record for a Minecraft server.

Firstly it parses the address, if it doesn't include port, tries SRV record, and if it's not there,
falls back on ``default_port``.

This function essentially mimics the address field of a minecraft java server. It expects an address like
'192.168.0.100:25565', if this address does contain a port, it will simply use it. If it doesn't, it will try
This function essentially mimics the address field of a Minecraft Java server. It expects an address like
``192.168.0.100:25565``, if this address does contain a port, it will simply use it. If it doesn't, it will try
to perform an SRV lookup, which if found, will contain the info on which port to use. If there's no SRV record,
this will fall back to the given default_port.
this will fall back to the given ``default_port``.

:param address:
The same address which would be used in minecraft's server address field.
Can look like: '127.0.0.1', or '192.168.0.100:12345', or 'mc.hypixel.net', or 'example.com:12345'.
Can look like: ``127.0.0.1``, or ``192.168.0.100:12345``, or ``mc.hypixel.net``, or ``example.com:12345``.
:param lifetime:
How many seconds a query should run before timing out.
Default value for this is inherited from dns.resolver.resolve
Default value for this is inherited from :func:`dns.resolver.resolve`.
:raises ValueError:
Either the address isn't valid and can't be parsed,
or it lacks a port, SRV record isn't present, and `default_port` wasn't specified.
or it lacks a port, SRV record isn't present, and ``default_port`` wasn't specified.
"""
host, port = _valid_urlparse(address)

Expand Down Expand Up @@ -205,10 +211,7 @@ async def async_minecraft_srv_address_lookup(
default_port: int | None = None,
lifetime: float | None = None,
) -> Address:
"""Parses the address, if it doesn't include port, tries SRV record, if it's not there, falls back on default_port

This function is an async alternative to minecraft_srv_address_lookup, check it's docstring for more details.
"""
"""Just an async alternative to :func:`.minecraft_srv_address_lookup`, check it for more details."""
host, port = _valid_urlparse(address)

# If we found a port in the address, there's nothing more we need
Expand Down
36 changes: 18 additions & 18 deletions mcstatus/dns.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,12 @@
def resolve_a_record(hostname: str, lifetime: float | None = None) -> str:
"""Perform a DNS resolution for an A record to given hostname

:param str hostname: The address to resolve for.
:param hostname: The address to resolve for.
:return: The resolved IP address from the A record
:raises dns.exception.DNSException:
One of the exceptions possibly raised by dns.resolver.resolve
Most notably this will be `dns.exception.Timeout`, `dns.resolver.NXDOMAIN` and `dns.resolver.NoAnswer`
One of the exceptions possibly raised by :func:`dns.resolver.resolve`.
Most notably this will be :exc:`dns.exception.Timeout`, :exc:`dns.resolver.NXDOMAIN`
and :exc:`dns.resolver.NoAnswer`
"""
answers = dns.resolver.resolve(hostname, RdataType.A, lifetime=lifetime)
# There should only be one answer here, though in case the server
Expand All @@ -23,9 +24,9 @@ def resolve_a_record(hostname: str, lifetime: float | None = None) -> str:


async def async_resolve_a_record(hostname: str, lifetime: float | None = None) -> str:
"""Asynchronous alternative to resolve_a_record.
"""Asynchronous alternative to :func:`.resolve_a_record`.

For more details, check the docstring of resolve_a_record function.
For more details, check it.
"""
answers = await dns.asyncresolver.resolve(hostname, RdataType.A, lifetime=lifetime)
# There should only be one answer here, though in case the server
Expand All @@ -38,11 +39,12 @@ async def async_resolve_a_record(hostname: str, lifetime: float | None = None) -
def resolve_srv_record(query_name: str, lifetime: float | None = None) -> tuple[str, int]:
"""Perform a DNS resolution for SRV record pointing to the Java Server.

:param str address: The address to resolve for.
:param query_name: The address to resolve for.
:return: A tuple of host string and port number
:raises dns.exception.DNSException:
One of the exceptions possibly raised by dns.resolver.resolve
Most notably this will be `dns.exception.Timeout`, `dns.resolver.NXDOMAIN` and `dns.resolver.NoAnswer`
One of the exceptions possibly raised by :func:`dns.resolver.resolve`.
Most notably this will be :exc:`dns.exception.Timeout`, :exc:`dns.resolver.NXDOMAIN`
and :exc:`dns.resolver.NoAnswer`
"""
answers = dns.resolver.resolve(query_name, RdataType.SRV, lifetime=lifetime)
# There should only be one answer here, though in case the server
Expand All @@ -54,9 +56,9 @@ def resolve_srv_record(query_name: str, lifetime: float | None = None) -> tuple[


async def async_resolve_srv_record(query_name: str, lifetime: float | None = None) -> tuple[str, int]:
"""Asynchronous alternative to resolve_srv_record.
"""Asynchronous alternative to :func:`.resolve_srv_record`.

For more details, check the docstring of resolve_srv_record function.
For more details, check it.
"""
answers = await dns.asyncresolver.resolve(query_name, RdataType.SRV, lifetime=lifetime)
# There should only be one answer here, though in case the server
Expand All @@ -70,21 +72,19 @@ async def async_resolve_srv_record(query_name: str, lifetime: float | None = Non
def resolve_mc_srv(hostname: str, lifetime: float | None = None) -> tuple[str, int]:
"""Resolve SRV record for a minecraft server on given hostname.

:param str address: The address, without port, on which an SRV record is present.
:param str hostname: The address, without port, on which an SRV record is present.
:return: Obtained target and port from the SRV record, on which the server should live on.
:raises dns.exception.DNSException:
One of the exceptions possibly raised by dns.resolver.resolve
Most notably this will be `dns.exception.Timeout`, `dns.resolver.NXDOMAIN` and `dns.resolver.NoAnswer`

Returns obtained target and port from the SRV record, on which
the minecraft server should live on.
One of the exceptions possibly raised by :func:`dns.resolver.resolve`.
Most notably this will be :exc:`dns.exception.Timeout`, :exc:`dns.resolver.NXDOMAIN`
and :exc:`dns.resolver.NoAnswer`.
"""
return resolve_srv_record("_minecraft._tcp." + hostname, lifetime=lifetime)


async def async_resolve_mc_srv(hostname: str, lifetime: float | None = None) -> tuple[str, int]:
"""Asynchronous alternative to resolve_mc_srv.
"""Asynchronous alternative to :func:`.resolve_mc_srv`.

For more details, check the docstring of resolve_mc_srv function.
For more details, check it.
"""
return await async_resolve_srv_record("_minecraft._tcp." + hostname, lifetime=lifetime)
Loading