.. 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`
