.. 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:: root
:type: str
The base URL of the BBSS directory
.. 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
.. doctest::
>>> site = bbss.site.Site('aleteoryx.me')
>>> for size in site.sizes:
... print(f"{size.entry} @ {size.url()}")
... if size.exists():
... for button in size.get():
... print(f"===> {button.entry} @ {button.url()}")
... else:
... print("...doesn't seem to exist!")
...
88x31 @ https://aleteoryx.me/BBSS/88x31/list.txt
===> ame.gif @ https://aleteoryx.me/BBSS/88x31/ame.gif
===> amev2.gif @ https://aleteoryx.me/BBSS/88x31/amev2.gif
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
.. 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
.. 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
bbss.buttons
============
.. py:module:: bbss.buttons
.. py:class:: ButtonListFileEntry(entry, comment, root)
A representation of a button image
:param str entry: The button's filename
:param comment: The comment for this button
:type comment: str or None
:param str root: The URL that this button is a child of
.. py:method:: url()
:return: The URL of the button file
:rtype: str
.. py:method:: exists()
:return: Whether the button actually exists on the server
:rtype: bool
.. py:method:: get()
:return: The HTTP response from trying to ``GET`` the button
:rtype: requests.Response
.. py:class:: ButtonListFile(contents)
A representation of a list of buttons
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 button list, if available
:rtype: ButtonListFile | None
.. doctest::
>>> buttons = bbss.buttons.ButtonListFile \
... .from_url("https://aleteoryx.me/BBSS/88x31/list.txt")
>>> for button in buttons:
... print(button.url())
...
https://aleteoryx.me/BBSS/88x31/ame.gif
https://aleteoryx.me/BBSS/88x31/amev2.gif
bbss.sizes
============
.. py:module:: bbss.sizes
.. py:class:: SizeListFileEntry(entry, comment, root)
A representation of a given size for buttons
:param str entry: The actual size
:param comment: The comment for this size
:type comment: str or None
:param str root: The BBSS directory that this size is within
.. py:method:: url()
:return: The URL of the size's button list
:rtype: str
.. py:method:: exists()
:return: Whether the size's button list file exists
:rtype: bool
.. py:method:: get()
:return: The actual button list, if available
:rtype: bbss.buttons.ButtonListFile
.. py:method:: dims()
:return: The dimensions of the size, ``(x, y)``, if they can be parsed from the name
:rtype: (int, int) or None
.. py:class:: SizeListFile(contents)
A representation of a list of button sizes
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 size list, if available
:rtype: ButtonListFile | None
bbss.friends
============
.. py:module:: bbss.friends
.. py:class:: FriendListFileEntry(entry, comment)
A representation of a friend site
:param str entry: The actual size
:param comment: The comment for this size
:type comment: str or None
.. py:attribute:: url
:type: str
The URL of the size's button list
.. py:attribute:: domain
:type: str
The domain of the friend site
.. py:attribute:: scheme
:type: str
The scheme of the friend site
.. py:attribute:: path
:type: str
The optional path of the remote BBSS directory
.. py:method:: exists()
:return: Whether the size's button list file exists
:rtype: bool
.. py:method:: get()
:return: The remote site
:rtype: bbss.site.Size
.. py:class:: FriendListFile(contents)
A representation of a list of friend sites
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 friend list, if available
:rtype: ButtonListFile | None
==================
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
