.. bbss.py documentation master file, created by
   sphinx-quickstart on Tue Dec  5 20:26:05 2023.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

.. role:: python(code)
   :language: python

=======
bbss.py
=======

For more information on BBSS itself, look `here <https://forum.melonland.net/index.php?topic=2047.0>`_.
This is a simple python module to allow for quickly scraping or exploring BBSS directories on sites.

bbss.site
=========

.. py:module:: bbss.site

   .. py:class:: Site(domain, path, *, scheme = 'https')

      A representation of some BBSS directory. On construction, all information about an individual site
      is downloaded.

      :param str domain: The domain to check for BBSS files

      :param path: An optional subdirectory to treat as the root of the BBSS directory
      :type path: str or None
      :param scheme: What protocol to download over
      :type scheme: 'http' | 'https'

      .. py:attribute:: default_path
         :type: bool

         Whether the site was generated from a default directory, or a user-supplied one

      .. py:attribute:: has_sizes_txt
         :type: bool

         Whether the BBSS directory contains a ``sizes.txt`` file

      .. py:attribute:: sizes
         :type: bbss.sizes.SizeListFile

         A list of the sizes found at the site

      .. py:attribute:: friends
         :type: Optional[bbss.friends.FriendListFile]

         A list of friend sites found at the site

bbss.lists
==========

.. py:module:: bbss.lists

   .. py:function:: parse_listfile[T](contents, ctor)

      Parses in the text of a listfile, and calls the passed constructor
      function repeatedly to generate datastructures.

      :param str contents: The contents of the listfile
      :param ctor: The constructor for the internal datastructures
      :type ctor: (str, str or None) -> T
      :return: A list of T, containing the contents of the file
      :rtype: list[T]

      .. doctest::

         >>> listfile = """
         ... entry 1
         ... ## this is a comment on entry two
         ... entry 2
         ... # omitted
         ... entry 3
         ... ## trailing comments are ignored
         ... """
         >>> bbss.lists.parse_listfile(listfile, lambda x, y: (x, y))
         [('entry 1', None), ('entry 2', 'this is a comment on entry two'), ('entry 3', None)]

   .. py:class:: ListFileEntry(entry, comment)

      The base class for all listfile entries.

      :param str entry: The main content of the entry
      :param comment: The comment, if present
      :type comment: str or None

   .. py:class:: BaseListFile(contents)

      The base class for all listfile representations.

      It supports all the :py:class:`collections.abc.Sequence` operations, meaning it can be used like a list in most cases.

      :param str contents: The contents of the source listfile

      .. py:classmethod:: from_url(url)

         Alternate constructor, which will attempt to download the listfile at ``url``.

         :param str url: The URL to download from.
         :return: A representation of the remote file, if available
         :rtype: BaseListFile | None

   .. py:class:: ListFile(contents)

      A representation of an arbitrary listfile.

      It supports all the :py:class:`collections.abc.Sequence` operations, meaning it can be used like a list in most cases.

      :param str contents: The contents of the source listfile

      .. py:classmethod:: from_url(url)

         Alternate constructor, which will attempt to download the listfile at ``url``.

         :param str url: The URL to download from.
         :return: A representation of the remote file, if available
         :rtype: BaseListFile | None

      .. doctest::

         >>> contents = """
         ... entry 1
         ... ## this is a comment on entry two
         ... entry 2
         ... # omitted
         ... entry 3
         ... ## trailing comments are ignored
         ... """
         >>> listfile = bbss.lists.ListFile(contents)
         >>> for entry in listfile:
         ...   print(">", entry.entry)
         ...   if entry.comment is not None:
         ...     print(f"  ``{entry.comment}''")
         ...
         > entry 1
         > entry 2
           ``this is a comment on entry two''
         > entry 3


==================
Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`