nntp.utils
==========

.. py:module:: nntp.utils

.. autoapi-nested-parse::

   An NNTP library - a bit more useful than the nntplib one (hopefully).
   Copyright (C) 2013-2020  Byron Platt

   This program is free software: you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation, either version 3 of the License, or
   (at your option) any later version.

   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License for more details.

   You should have received a copy of the GNU General Public License
   along with this program.  If not, see <http://www.gnu.org/licenses/>.



Functions
---------

.. autoapisummary::

   nntp.utils.unparse_range
   nntp.utils.unparse_msgid_range
   nntp.utils.parse_newsgroup
   nntp.utils._parse_header
   nntp.utils.parse_headers
   nntp.utils._unparse_header
   nntp.utils.unparse_headers
   nntp.utils.parse_date
   nntp.utils.parse_epoch


Module Contents
---------------

.. py:function:: unparse_range(obj: nntp.types.Range) -> str

   Unparse a range argument.

   Args:
       obj: An article range. There are a number of valid formats; an integer
           specifying a single article or a tuple specifying an article range.
           If the range doesn't specify a last article then all articles from
           the first specified article up to the current last article for the
           group are included.

   Returns:
       The range as a string that can be used by an NNTP command.

   Note: Sample valid formats.
       4678
       (4245,)
       (4245, 5234)


.. py:function:: unparse_msgid_range(obj: str | nntp.types.Range) -> str

   Unparse a message-id or range argument.

   Args:
       obj: A message id as a string or a range as specified by
           unparse_range().

   Raises:
       ValueError: If obj is not a valid message id or range format. See
           unparse_range() for valid range formats.

   Returns:
       A message id or range as a string that can be used by an NNTP command.


.. py:function:: parse_newsgroup(line: str) -> nntp.types.Newsgroup

   Parse a newsgroup info line to python types.

   Args:
       line: An info response line containing newsgroup info.

   Returns:
       A tuple of group name, low-water as integer, high-water as integer and
       posting status.

   Raises:
       ValueError: If the newsgroup info cannot be parsed.

   Note:
       Posting status is a character is one of (but not limited to):
           "y" posting allowed
           "n" posting not allowed
           "m" posting is moderated


.. py:function:: _parse_header(line: str) -> str | tuple[str, str] | None

   Parse a header line.

   Args:
       line: A header line as a string.

   Returns:
       None if end of headers is found. A string giving the continuation line
       if a continuation is found. A tuple of name, value when a header line
       is found.

   Raises:
       ValueError: If the line cannot be parsed as a header.


.. py:function:: parse_headers(obj: str | collections.abc.Iterable[str]) -> nntp.headerdict.HeaderDict

   Parse a string a iterable object (including file like objects) to a
   python dictionary.

   Args:
       obj: An iterable object including file-like objects.

   Returns:
       An dictionary of headers. If a header is repeated then the last value
       for that header is given.

   Raises:
       ValueError: If the first line is a continuation line or the headers
           cannot be parsed.


.. py:function:: _unparse_header(name: str, value: str) -> str

   Parse a name value tuple to a header string.

   Args:
       name: The header name.
       value: the header value.

   Returns:
       The header as a string.


.. py:function:: unparse_headers(hdrs: collections.abc.Mapping[str, str]) -> str

   Parse a dictionary of headers to a string.

   Args:
       hdrs: A dictionary of headers.

   Returns:
       The headers as a string that can be used in an NNTP POST.


.. py:function:: parse_date(value: str | int) -> datetime.datetime

   Parse a date as returned by the `DATE` command.

   Args:
       value: A date as a string in the format `YYYYMMDDHHMMSS`.

   Returns:
       A datetime object representing the date with timezone set to UTC.

   Raises:
       ValueError: If the value cannot be parsed.


.. py:function:: parse_epoch(value: str | int) -> datetime.datetime

   Parse a date as returned by the `DATE` command.

   Args:
       line: An epoch date as a string.

   Returns:
       A datetime object representing the date with timezone set to UTC.

   Raises:
       ValueError: If the value cannot be parsed.