Prepare for release 0.1.0b0 (#752)

Author: chrisrink10

.readthedocs.yaml

@@ -3,7 +3,7 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.10"
+    python: "3.12"
 
 sphinx:
    configuration: docs/conf.py

CHANGELOG.md

@@ -5,6 +5,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+
+## [v0.1.0b0]
 ### Added
  * Added rudimentary support for `clojure.stacktrace` with `print-cause-trace` (part of #721)
  * Added support for `bytes` literals using a `#b` prefix (#732)
@@ -393,6 +395,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - Basilisp language and compiler base.
 
+[v0.1.0b0]: https://github.com/chrisrink10/basilisp/compare/v0.1.0a2..v0.1.0b0
 [v0.1.0a2]: https://github.com/chrisrink10/basilisp/compare/v0.1.0a1..v0.1.0a2
 [v0.1.0a1]: https://github.com/chrisrink10/basilisp/compare/v0.1.dev15..v0.1.0a1
 [v0.1.dev15]: https://github.com/chrisrink10/basilisp/compare/v0.1.dev14..v0.1.dev15

docs/compiler.rst

@@ -176,7 +176,7 @@ Debugging
 
 The compiler generates Python code by generating Python AST nodes, rather than emitting the raw Python code as text.
 This is convenient for the compiler, but inspecting Python AST nodes manually for bugs can be a bit of a challenge even with a debugger.
-For this reason, the Basilisp compiler can also use the `astor <https://github.com/berkerpeksag/astor>`_ library to generate raw Python code for visual inspection.
+For this reason, the Basilisp compiler can also use the `ast.unparse <https://docs.python.org/3/library/ast.html#ast.unparse>`_ (`astor <https://github.com/berkerpeksag/astor>`_ in versions of Python prior to 3.9) library to generate raw Python code for visual inspection.
 
 Currently, the compiler is configured to automatically generate Python code for all namespaces.
 This code generation isn't slow, but it does add an appreciable amount of time to the compilation of each individual namespace.
@@ -185,4 +185,16 @@ This setting will be changed to be off by default once Basilisp is in a stable r
 
 .. code-block:: bash
 
-   export BASILISP_EMIT_GENERATED_PYTHON=false
+   export BASILISP_EMIT_GENERATED_PYTHON=false
+
+Logging
+^^^^^^^
+
+Basilisp ships with a disabled Python ``logger`` set to ``WARNING``.
+For development, it may be useful to enable the logger or to change its log level.
+The former can be configured via the environment variable ``BASILISP_USE_DEV_LOGGER``, while the latter may be set by ``BASILISP_LOGGING_LEVEL``.
+
+.. code-block:: bash
+
+   export BASILISP_USE_DEV_LOGGER=true
+   export BASILISP_LOGGING_LEVEL=INFO

docs/conf.py

@@ -56,7 +56,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.

docs/contributing.rst

@@ -45,6 +45,8 @@ Developers should generate their own lock file and update it regularly during de
 
 Additionally, `pyenv <https://github.com/pyenv/pyenv>`_ is recommended to manage versions of Python readily on your local development environment.
 Setup of ``pyenv`` is somewhat more specific to your environment, so see the documentation in the repository for more information.
+Developers should install all supported versions of Python and configure them for the project using ``pyenv local`` in the Basilisp source directory.
+The ``.python-version`` file is included in the project ``.gitignore``.
 
 .. _getting_started_development:
 
@@ -57,24 +59,42 @@ To prepare your `poetry` environment, you need to install dependencies:
 
    poetry install
 
-Afterwards, you can start up the REPL for development with a simple:
+Afterwards, you can open a new Poetry shell to start up the REPL for development.
+The ``make repl`` target _may_ be sufficient for local development, though developers working on the Basilisp compiler or standard library are encouraged to enable a more verbose set of configurations for detecting issues during development.
+The command below enables the highest level of logging and disables namespace caching, both of which can help reveal otherwise hidden issues during development.
 
 .. code-block:: bash
 
-   make repl
+   poetry shell
+   BASILISP_USE_DEV_LOGGER=true BASILISP_LOGGING_LEVEL=TRACE BASILISP_DO_NOT_CACHE_NAMESPACES=true basilisp repl
+
+Developers working on the Basilisp compiler should periodically update their dependencies to ensure no incompatibilities have been introduced into the codebase with new dependency versions.
+
+.. code-block:: bash
+
+   poetry update
 
 .. _linting_testing_and_type_checking:
 
 Linting, Running Tests, and Type Checking
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Basilisp automates linting, running tests, and type checking using `Tox <https://github.com/tox-dev/tox>`_.
-All three steps can be performed using a provided ``make`` target:
+All three steps can be performed across all supported versions of CPython using a provided ``make`` target:
 
 .. code-block:: bash
 
    make test
 
+To run a more targeted CI check directly from within the Poetry shell, developers can use ``tox`` commands directly.
+For instance, to run only the tests for ``basilisp.io`` on Python 3.12, you could use the following command:
+
+.. code-block:: bash
+
+   tox run -e py312 -- tests/basilisp/test_io.lpy
+
+Developers are encouraged to investigate the available configurations in ``tox.ini`` to determine which CI targets they will have at their disposal.
+
 Testing is performed using `PyTest <https://github.com/pytest-dev/pytest/>`_.
 Type checking is performed by `MyPy <http://mypy-lang.org/>`_.
 Linting is performed using `PyLint <https://github.com/pylint-dev/pylint>`_ and `Ruff <https://github.com/astral-sh/ruff>`_.

docs/differencesfromclojure.rst

@@ -192,7 +192,10 @@ Core Libraries
 Basilisp includes ports of some of the standard libraries from Clojure which should generally match the source in functionality.
 
 * :lpy:ns:`basilisp.data` is a port of ``clojure.data``
+* :lpy:ns:`basilisp.edn` is a port of ``clojure.edn``
+* :lpy:ns:`basilisp.io` is a port of ``clojure.java.io``
 * :lpy:ns:`basilisp.set` is a port of ``clojure.set``
+* :lpy:ns:`basilisp.shell` is a port of ``clojure.java.shell``
 * :lpy:ns:`basilisp.string` is a port of ``clojure.string``
 * :lpy:ns:`basilisp.test` is a port of ``clojure.test``
 * :lpy:ns:`basilisp.walk` is a port of ``clojure.walk``

docs/features.rst

@@ -5,7 +5,7 @@ Features
 
 Here are a few of Basilisp's great features:
 
-* Immutable data structures, backed by `Pyrsistent <https://github.com/tobgu/pyrsistent>`_
+* Immutable data structures, backed by `Immutables <https://github.com/MagicStack/immutables>`_ and `Pyrsistent <https://github.com/tobgu/pyrsistent>`_
 * Strong emphasis on functional programming concepts
 * Access to the vast array of existing Python libraries
 * Seamless :ref:`interoperability <python_interop>` between Python code and Basilisp code

docs/gettingstarted.rst

@@ -78,7 +78,7 @@ Basilisp source files should always have a ``.lpy`` extension.
    Python ``__init__.py`` files are not required anywhere in Basilisp projects (including for nested namespaces), though you may need to use them if your project mixes Python and Basilisp sources.
 
 Basilisp apps can use any of Python's myriad dependency management options, including `pip <https://pip.pypa.io/en/stable/>`_, `Pipenv <https://pipenv.pypa.io/en/latest/>`_, and `Poetry <https://python-poetry.org/>`_.
-Basilisp itself uses Poetry and that is the recommended
+Basilisp itself uses Poetry and that is the recommended dependency management tool for new Basilisp projects.
 
 .. _bootstrapping:
 

docs/reader.rst

@@ -487,6 +487,8 @@ Basilisp takes advantage of this in :lpy:ns:`basilisp.io`.
          :lpy38+ (.unlink (as-path f) ** :missing-ok (if silently true false)))
       silently))
 
+.. _python_platform_reader_features:
+
 Platform Reader Features
 ^^^^^^^^^^^^^^^^^^^^^^^^
 

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "basilisp"
-version = "0.1.0a2"
+version = "0.1.0b0"
 description = "A Clojure-like lisp written for Python"
 authors = ["Christopher Rink <[email protected]>"]
 license = "Eclipse Public License 1.0 (EPL-1.0)"

src/basilisp/contrib/bencode.lpy

@@ -86,7 +86,7 @@
   - ``int``
   - ``str``, which is first decided to UTF-8 ``bytes``
   - keywords and symbols, which are first converted to strings (including namespace,
-    separated by '/') and then converted using the rules for ``str``s
+    separated by '/') and then converted using the rules for ``str`` s
   - Python ``list``
   - ``tuple``
   - Basilisp lists and vectors

src/basilisp/io.lpy

@@ -78,8 +78,7 @@
 
 (defn- clean-writer-mode
   [opts]
-  (let [append?    (:append opts)
-        mode       (:mode opts "")
+  (let [mode       (:mode opts "")
         clean-mode (cond
                      (:append opts)                 (str "a" mode)
                      (not (str/includes? mode "w")) (str "w" mode)