{"version":"https:\/\/jsonfeed.org\/version\/1","title":"mathspp.com feed","home_page_url":"https:\/\/mathspp.com\/blog\/til","feed_url":"https:\/\/mathspp.com\/blog\/til.json","description":"Stay up-to-date with the articles on mathematics and programming that get published to mathspp.com.","author":{"name":"Rodrigo Gir\u00e3o Serr\u00e3o"},"items":[{"title":"TIL #145 \u2013 collections.deque is implemented in blocks","date_published":"2026-05-20T09:25:00+02:00","id":"https:\/\/mathspp.com\/blog\/til\/collections-deque-is-implemented-in-blocks","url":"https:\/\/mathspp.com\/blog\/til\/collections-deque-is-implemented-in-blocks","content_html":"

Today I learned that collections.deque<\/code> is implemented as a doubly-linked list of blocks.<\/p>\n\n

collections.deque<\/code><\/a><\/h2>\n

I've written about the data structure deque<\/code> from the module collections<\/code> extensively.\nIn particular, I wrote a deque<\/code> tutorial with plenty of practical example use cases of deque<\/code><\/a>.<\/p>\n

Today, after some discussion during a cohort I was teaching, a student sent a link to the collections.deque<\/code> source code<\/a> where a comment explains some of the lower-level details of how a deque<\/code> is implemented.<\/p>\n

Double-ended queue<\/a><\/h2>\n

The name “deque” stands for Double-Ended QUEue and that's because a deque is a doubly-linked list.\nWhen you learn about that, you might think that, under the hood, a deque<\/code> is essentially a collection of nodes that link to the next and to the previous:<\/p>\n

class Node:\n    prev_node: Node | None\n    value: object\n    next_node: Node | None\n\nclass deque:\n    first_node: Node | None\n    last_node: Node | None\n    ...<\/code><\/pre>\n
But that's not the case.\nApparently, a deque<\/code> is implemented in a more optimised way, where each “node” is actually a block that can hold up to a certain number of elements.\nAt the level of C, this means you need to manipulate memory less often, which makes the deque<\/code> faster.<\/p>\n
Pseudo-implementation of deque<\/code> in Python<\/a><\/h2>\n
The Python code below is a pseudo-implementation of deque<\/code> that mimics more or less the underlying block mechanism that's in place for Python 3.15 (and that has been in place for decades<\/em>).\nThe Python code below is stripped of all of the memory operations and other lower-level details and instead focuses on the mechanics of managing blocks:<\/p>\n
from dataclasses import dataclass, field\n\nBLOCKLEN = 64\nCENTRE = (BLOCKLEN - 1) \/\/ 2\n\ndef new_empty_block_data() -> list[object]:\n    return [None for _ in range(BLOCKLEN)]\n\n@dataclass\nclass Block:\n    left_link: Block | None = None\n    data: list[object] = field(default_factory=new_empty_block_data)\n    right_link: Block | None = None\n\n@dataclass(init=False)\nclass deque:\n    left_block: Block\n    right_block: Block\n    left_index: int\n    right_index: int\n    maxlen: int\n\n    def __init__(self, maxlen: int | None = None) -> None:\n        self.left_block = self.right_block = Block()\n        self.left_index = CENTRE + 1\n        self.right_index = CENTRE\n        if maxlen is None:\n            maxlen = -1\n        self.maxlen = maxlen<\/code><\/pre>\n
The two classes Block<\/code> and deque<\/code> set the structure for the deque<\/code>.\nThe attributes left_block<\/code> and right_block<\/code> point, respectively, to the leftmost block and the rightmost block, and the first item of a deque d<\/code> is always found at d.left_block[d.left_index]<\/code> while the last item is at d.right_block[d.right_index]<\/code>.<\/p>\n
With this in mind, adding or removing elements from a deque is a matter of managing the blocks and the indices correctly.\nBelow, you can find the pseudo-implementation of append<\/code> and pop<\/code>:<\/p>\n
@dataclass\nclass deque:\n    ...\n\n    def append(self, item: object) -> None:\n        # If there's no space, create a new block.\n        if self.right_index == BLOCKLEN - 1:\n            new_block = Block()\n            self.right_block.right_link = new_block\n            new_block.left_link = self.right_block\n            self.right_block = new_block\n            self.right_index = -1\n\n        self.right_index += 1\n        self.right_block[self.right_index] = item\n\n        if self.maxlen > -1 and len(self) > self.maxlen:\n            self.popleft()\n\n    def pop(self) -> object:\n        item = self.right_block[self.right_index]\n        self.right_index -= 1\n\n        #...<\/code><\/pre>","summary":"Today I learned that collections.deque is implemented as a doubly-linked list of blocks.","date_modified":"2026-05-20T10:54:10+02:00","image":"\/user\/pages\/02.blog\/04.til\/145.collections-deque-is-implemented-in-blocks\/thumbnail.webp"},{"title":"TIL #144 \u2013 Sentinel built-in","date_published":"2026-05-01T19:49:00+02:00","id":"https:\/\/mathspp.com\/blog\/til\/sentinel-builtin","url":"https:\/\/mathspp.com\/blog\/til\/sentinel-builtin","content_html":"
Today I learned Python 3.15 will get a new sentinel built-in.<\/p>\n\n
Sentinel values are unique placeholder values that are commonly used in programming.\nPython 3.15 ships with a new built-in sentinel<\/code> that can be used to create new sentinel values:<\/p>\n
# Python 3.15+\n>>> MISSING = sentinel(\"MISSING\")\n>>> MISSING\nMISSING<\/code><\/pre>\n
Before this built-in was added, the most common sentinel idiom used the built-in object<\/code>:<\/p>\n
MISSING = object()\n\ndef my_function(some_arg=MISSING):\n    if some_arg is MISSING:\n        ... # Handle the sentinel<\/code><\/pre>\n
In the function above, the sentinel value MISSING<\/code> is being used to check whether the user passed anything<\/em> as the parameter some_arg<\/code> or not.\nPEP 661<\/a>, that introduced this built-in, has a great discussion covering the reasons as to why this pattern, and many other sentinel patterns, fall short.\nIn general, each common sentinel idiom suffers from at least one of the following problems:<\/p>\n
    \n
  1. Bad string repr<\/strong>: the string representation<\/a> is too long and uninformative<\/li>\n
  2. Type unsafe<\/strong>: the sentinels don't have a distinct type so it becomes hard or impossible to write code that uses the sentinels and is type safe<\/li>\n
  3. Unexpected copy behaviour<\/strong>: the sentinels can't be copied or pickled without breaking the sentinel behaviour<\/li>\n<\/ol>","summary":"Today I learned Python 3.15 will get a new sentinel built-in.","date_modified":"2026-05-01T21:18:58+02:00","tags":["programming","python"],"image":"\/user\/pages\/02.blog\/04.til\/144.sentinel-builtin\/thumbnail.webp"},{"title":"TIL #143 \u2013 Resolve a lazy import manually","date_published":"2026-04-27T17:18:00+02:00","id":"https:\/\/mathspp.com\/blog\/til\/resolve-a-lazy-import-manually","url":"https:\/\/mathspp.com\/blog\/til\/resolve-a-lazy-import-manually","content_html":"
    Learn how to work around the Python machinery to resolve an explicit lazy import manually.<\/p>\n\n
    A couple of articles ago I wrote about how you could inspect a lazy import<\/a>.<\/p>\n
    Apparently, you can use a similar trick to check the attributes and methods that a lazy import has:<\/p>\n
    >>> lazy import json\n>>> dir(globals()[\"json\"])\n['__class__', '__delattr__', '__dir__', '__doc__', '__eq__', '__format__', '__ge__', '__getattribute__', '__getstate__', '__gt__', '__hash__', '__init__', '__init_subclass__', '__le__', '__lt__', '__ne__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__setattr__', '__sizeof__', '__str__', '__subclasshook__', 'resolve']<\/code><\/pre>\n
    Apart from a large number of dunder methods<\/a> and dunder attributes, you'll find the method resolve<\/code>.\nYou can run help(globals()[\"json\"].resolve)<\/code> to get the help text on that method:<\/p>\n
    Help on built-in function resolve:\n\nresolve() method of builtins.lazy_import instance\n    resolves the lazy import and returns the actual object<\/code><\/pre>\n
    This shows that it's the method resolve<\/code> that resolves a lazy import.<\/p>\n
    If you call the method, you can get access to the resolved module:<\/p>\n
    >>> lazy import json\n>>> resolved_json = globals()[\"json\"].resolve()\n>>> resolved_json\n<module 'json' from '\/Users\/rodrigogs\/.local\/share\/uv\/python\/cpython-3.15.0a8-macos-aarch64-none\/lib\/python3.15\/json\/__init__.py'><\/code><\/pre>\n
    After calling resolve<\/code>, the lazy module doesn't disappear automatically:<\/p>\n
    >>> globals()[\"json\"]\n<lazy_import 'json'><\/code><\/pre>\n
    Which shows that the mechanism that's responsible for reification most likely<\/em> calls the method resolve<\/code> and then reassigns<\/em> the name of the module to the module returned by resolve<\/code>.\nIn a way, it's as if the reification process ran something like<\/p>\n
    globals()[\"json\"] = globals()[\"json\"].resolve()<\/code><\/pre>\n
    In hindsight, this isn't too surprising.\nAfter all, Python tends to be very consistent.\nThe only mistery that remains is what<\/em> triggers the reification process.\nHow is it that Python can detect when something touches<\/em> the lazy import..?<\/p>","summary":"Learn how to work around the Python machinery to resolve an explicit lazy import manually.","date_modified":"2026-04-27T18:29:12+02:00","tags":["programming","python"],"image":"\/user\/pages\/02.blog\/04.til\/143.resolve-a-lazy-import-manually\/thumbnail.webp"},{"title":"TIL #142 \u2013 Cyclic quadrilateral","date_published":"2026-03-14T14:58:00+01:00","id":"https:\/\/mathspp.com\/blog\/til\/cyclic-quadrilateral","url":"https:\/\/mathspp.com\/blog\/til\/cyclic-quadrilateral","content_html":"
    Today I learned that cyclic quadrilaterals have supplementary opposite angles.<\/p>\n\n
    A cyclic quadrilateral<\/strong> \u2014 a quadrilateral whose four vertices all lie on a single circle \u2014 has supplementary opposite angles.<\/p>\n
    This means that opposite angles add to 180 degrees, or \\(\\pi\\)<\/span> radians.<\/p>\n
    As it turns out, this is actually an equivalence relation.\nIf a quadrilateral has supplementary opposite angles, it's a cyclic quadrilateral.<\/p>\n
    This fact about supplementary opposite angles was very useful for an animation I was trying to create...\nI may share it here later!<\/p>","summary":"Today I learned that cyclic quadrilaterals have supplementary opposite angles.","date_modified":"2026-03-14T16:03:32+01:00","tags":["mathematics","geometry"],"image":"\/user\/pages\/02.blog\/04.til\/142.cyclic-quadrilateral\/thumbnail.webp"},{"title":"TIL #141 \u2013 Inspect a lazy import","date_published":"2026-03-13T14:38:00+01:00","id":"https:\/\/mathspp.com\/blog\/til\/inspect-a-lazy-import","url":"https:\/\/mathspp.com\/blog\/til\/inspect-a-lazy-import","content_html":"
    Today I learned how to inspect a lazy import object in Python 3.15.<\/p>\n\n
    Python 3.15 comes with lazy imports and today I played with them for a minute.\nI defined the following module mod.py<\/code>:<\/p>\n
    print(\"Hey!\")\n\ndef f():\n    return \"Bye!\"<\/code><\/pre>\n
    Then, in the REPL, I could check that lazy imports indeed work:<\/p>\n
    >>> # Python 3.15\n>>> lazy import mod\n>>><\/code><\/pre>\n
    The fact that I didn't see a \"Hey!\" means that the import is, indeed, lazy.\nThen, I wanted to take a look at the module so I printed it, but that triggered reification (going from a lazy import to a regular module):<\/p>\n
    >>> print(mod)\nHey!\n<module 'mod' from '\/Users\/rodrigogs\/Documents\/tmp\/mod.py'><\/code><\/pre>\n
    So, I checked the PEP that introduced explicit lazy modules<\/a> and turns out as soon as you reference<\/em> the lazy object directly, it gets reified.\nBut you can work around it by using globals<\/code>:<\/p>\n
    >>> # Fresh 3.15 REPL\n>>> lazy import mod\n>>> globals()[\"mod\"]\n<lazy_import 'mod'><\/code><\/pre>\n
    This shows the new class lazy_import<\/code> that was added to support lazy imports!<\/p>\n
    Pretty cool, right?<\/p>","summary":"Today I learned how to inspect a lazy import object in Python 3.15.","date_modified":"2026-03-13T15:54:14+01:00","tags":["programming","python"],"image":"\/user\/pages\/02.blog\/04.til\/141.inspect-a-lazy-import\/thumbnail.webp"},{"title":"TIL #140 \u2013 Install Jupyter with uv","date_published":"2026-03-03T16:16:00+01:00","id":"https:\/\/mathspp.com\/blog\/til\/install-jupyter-with-uv","url":"https:\/\/mathspp.com\/blog\/til\/install-jupyter-with-uv","content_html":"
    Today I learned how to install jupyter properly while using uv to manage tools.<\/p>\n\n
    Running a Jupyter notebook server or Jupyter lab<\/a><\/h2>\n
    To run a Jupyter notebook server with uv, you can run the command<\/p>\n
    $ uvx jupyter notebook<\/code><\/pre>\n
    Similarly, if you want to run Jupyter lab, you can run<\/p>\n
    $ uvx jupyter lab<\/code><\/pre>\n
    Both work, but uv will kindly present a message explaining how it's actually doing you a favour, because it guessed<\/em> what you wanted.\nThat's because uvx something<\/code> usually looks for a package named \u201csomething\u201d with a command called \u201csomething\u201d.<\/p>\n
    As it turns out, the command jupyter<\/code> comes from the package jupyter-core<\/code>, not from the package jupyter<\/code>.<\/p>\n
    Installing Jupyter<\/a><\/h2>\n
    If you're running Jupyter notebooks often, you can install the notebook server and Jupyter lab with<\/p>\n
    $ uv tool install --with jupyter jupyter-core<\/code><\/pre>\n
    Why uv tool install jupyter<\/code> fails<\/a><\/h3>\n
    Running uv tool install jupyter<\/code> fails because the package jupyter<\/code> doesn't provide any commands by itself.<\/p>\n
    Why uv tool install jupyter-core<\/code> doesn't work<\/a><\/h3>\n
    The command uv tool install jupyter-core<\/code> looks like it works because it installs the command jupyter<\/code> correctly.\nHowever, if you use --help<\/code> you can see that you don't have access to the subcommands you need:<\/p>\n
    $ uv tool install jupyter-core\n...\nInstalled 3 executables: jupyter, jupyter-migrate, jupyter-troubleshoot\n$ jupyter --help\n...\nAvailable subcommands: book migrate troubleshoot<\/code><\/pre>\n
    That's because the subcommands notebook<\/code> and lab<\/code> are from the package jupyter<\/code>.\nThe solution?\nInstall jupyter-core<\/code> with<\/em> the additional dependency jupyter<\/code>, which is what the command uv tool install --with jupyter jupyter-core<\/code> does.<\/p>\n
    Other usages of Jupyter<\/a><\/h2>\n
    The uv documentation has a page dedicated exclusively to the usage of uv with Jupyter<\/a>, so check it out for other use cases of the uv and Jupyter combo!<\/p>","summary":"Today I learned how to install jupyter properly while using uv to manage tools.","date_modified":"2026-03-03T18:05:58+01:00","tags":["python","programming","uv","productivity"],"image":"\/user\/pages\/02.blog\/04.til\/140.install-jupyter-with-uv\/thumbnail.webp"},{"title":"TIL #139 \u2013 Multiline input in the REPL","date_published":"2026-03-02T15:15:00+01:00","id":"https:\/\/mathspp.com\/blog\/til\/multiline-input-in-the-repl","url":"https:\/\/mathspp.com\/blog\/til\/multiline-input-in-the-repl","content_html":"
    Today I learned how to do multiline input in the REPL using an uncommon combination of arguments for the built-in open<\/code>.<\/p>\n\n
    A while ago I learned I could use open(0)<\/code> to open standard input<\/a>.\nThis unlocks a neat trick that allows you to do multiline input in the REPL:<\/p>\n
    >>> msg = open(0).read()\nHello,\nworld!\n^D\n>>> msg\n'Hello,\\nworld!\\n'<\/code><\/pre>\n
    The cryptic ^D<\/code> is Ctrl<\/kbd>+D<\/kbd>, which means EOF on Unix systems.\nIf you're on Windows, use Ctrl<\/kbd>+Z<\/kbd>.<\/p>\n
    The problem is that if you try to use open(0).read()<\/code> again to read more multiline input, you get an exception:<\/p>\n
    OSError: [Errno 9] Bad file descriptor<\/code><\/pre>\n
    That's because, when you finished reading the first time around, Python closed the file descriptor 0<\/code>, so you can no longer use it.<\/p>\n
    The fix is to set closefd=False<\/code> when you use the built-in open<\/code>.\nWith the parameter closefd<\/code> set to False<\/code>, the underlying file descriptor isn't closed and you can reuse it:<\/p>\n
    >>> msg1 = open(0, closefd=False).read()\nHello,\nworld!\n^D\n>>> msg1\n'Hello,\\nworld!\\n'\n\n>>> msg2 = open(0, closefd=False).read()\nGoodbye,\nworld!\n^D\n>>> msg2\n'Goodbye,\\nworld!\\n'<\/code><\/pre>\n
    By using open(0, closefd=False)<\/code>, you can read multiline input in the REPL repeatedly<\/em>.<\/p>","summary":"Today I learned how to do multiline input in the REPL using an uncommon combination of arguments for the built-in open.","date_modified":"2026-03-02T16:21:46+01:00","tags":["repl","programming","python"],"image":"\/user\/pages\/02.blog\/04.til\/139.multiline-input-in-the-repl\/thumbnail.webp"},{"title":"TIL #138 \u2013 Custom directives in Jupyter Book","date_published":"2026-01-02T22:22:00+01:00","id":"https:\/\/mathspp.com\/blog\/til\/custom-directives-in-jupyter-book","url":"https:\/\/mathspp.com\/blog\/til\/custom-directives-in-jupyter-book","content_html":"
    Today I learned how to create and register a simple Sphinx extension to use as a custom directive in a Jupyter Book project.<\/p>\n\n
    I wanted to create a custom directive that I could use in a Jupyter Book<\/a> project that would look like this:<\/p>\n
    Some prose goes here.\n\n```{mypy} snippet.py\n```<\/code><\/pre>\n
    Then, the directive {mypy}<\/code> would run mypy against the file snippet.py<\/code> and include the mypy output in the book.<\/p>\n
    With the help of ChatGPT I was able to quickly whip up a Sphinx extension that defines this directive, including the ability to infer the location of my Python snippets based on the concrete structure I have for this project I'm working on: a file snippet.py<\/code> mentioned in a chapter called xx.my-chapter.md<\/code> can be found in snippets\/my-chapter\/snippet.py<\/code>, where snippets<\/code> is at the root of the project.<\/p>\n
    After a bit of back and forth and some manual tweaks, this is the directive I ended up with:<\/p>\n
    _ext\/mypy_directive.py<\/code><\/summary>
    \"\"\"\nCreates a Sphinx directive {mypy} that runs mypy on the given file and includes the output.\nWhen used as ```{mypy} script.py in a file called `xx.some-chapter.md`, this directive\nwill try to find the file in `snippets\/some-chapter\/script.py`.\nIf the file argument contains slashes, it is interpreted as an absolute path.\n\"\"\"\n\nfrom __future__ import annotations\n\nimport subprocess\nfrom pathlib import Path\nfrom typing import Any, List\n\nfrom docutils import nodes\nfrom sphinx.util.docutils import SphinxDirective\n\nclass MypyDirective(SphinxDirective):\n    \"\"\"\n    Usage (MyST):\n        ```{mypy} path\/to\/file.py\n        :flags: --strict --show-error-codes\n        ```\n    \"\"\"\n\n    required_arguments = 1  # the file path\n    optional_arguments = 0\n    has_content = False\n\n    option_spec = {\n        \"flags\": lambda s: s,  # pass extra mypy CLI flags as a single string\n    }\n\n    def run(self) -&gt; List[nodes.Node]:\n        script_arg = self.arguments[0]\n        env = self.env\n\n        # Get current document filename (e.g. \"given-chapter\")\n        # env.docname is like \"chapters\/given-chapter\" (no extension)\n        _, _, chapter_name = Path(env.docname).name.partition(\".\")\n\n        # If the user passed just \"script.py\", infer snippets\/<chapter>\/<script.py>.\n        # If they passed a path with a slash, treat it as explicit.\n        if \"\/\" not in script_arg and \"\\\\\" not in script_arg:\n            inferred_rel = str(Path(\"snippets\") \/ chapter_name \/ script_arg)\n        else:\n            inferred_rel = script_arg\n\n        # Sphinx helper: resolve filenames relative to doc, and track dependencies\n        _, abs_path_str = env.relfn2path(inferred_rel)\n        abs_path = Path(abs_path_str)\n\n        # Ensure rebuilds happen when the file changes\n        env.note_dependency(str(abs_path))\n\n        if not abs_path.exists():\n            msg = f\"[mypy] File not found: {abs_path}\"\n            return [nodes.literal_block(text=msg)]\n\n        flags = self.options.get(\"flags\", \"\").strip()\n        cmd: list[str] = [\"mypy\", str(abs_path)]\n        if flags:\n            cmd.extend(flags.split())\n\n        proc = subprocess.run(\n            cmd,\n            stdout=subprocess.PIPE,\n            stderr=subprocess.STDOUT,\n            text=True,\n            cwd=abs_path.parent,\n        )\n\n        output = proc.stdout.rstrip()\n        if not output:\n            output = \"[mypy] (no output)\"\n\n        output = f\"$ mypy {abs_path.name}\\n\" + output\n\n        # Render as a literal block (monospace). “language” here is just for CSS\/classes.\n        block = nodes.literal_block(output, output)\n        block[\"language\"] = \"text\"\n        return [block]\n\ndef setup(app: Any) -&gt; dict[str, Any]:\n    app.add_directive(\"mypy\", MypyDirective)\n    return {\"version\": \"0.1\", \"parallel_read_safe\": True, \"parallel_write_safe\": True}<\/code><\/pre>\n
    <\/script.py><\/p>\n<\/details>
    To be able to use it, I had to tweak the book configuration to tell it where to find my extension:<\/p>\n
    sphinx:\n  ...\n  local_extensions:\n    mypy_directive: _ext\n  extra_extensions:\n    - mypy_directive<\/code><\/pre>\n
    This assumes the code mypy_directive.py<\/code> lives inside _ext<\/code> in...<\/p>","summary":"Today I learned how to create and register a simple Sphinx extension to use as a custom directive in a Jupyter Book project.","date_modified":"2026-07-06T16:16:52+02:00","tags":["productivity","llms"],"image":"\/user\/pages\/02.blog\/04.til\/138.custom-directives-in-jupyter-book\/thumbnail.webp"},{"title":"TIL #137 \u2013 Inline SVGs in Jupyter notebooks","date_published":"2025-11-23T23:34:00+01:00","id":"https:\/\/mathspp.com\/blog\/til\/inline-svgs-in-jupyter-notebooks","url":"https:\/\/mathspp.com\/blog\/til\/inline-svgs-in-jupyter-notebooks","content_html":"
    Today I learned how to inline SVGs in Jupyter notebooks in two simple steps.<\/p>\n\n
    Today I learned how to inline SVGs in Jupyter notebooks in two simple steps:<\/p>\n
      \n
    1. URL-encode the SVG markup. If you have an SVG file, open it and copy the contents of the file starting from the <svg><\/code> tag all the way up to the closing <\/svg><\/code> and encode it so it's safe to use in a URL. You can use this URL encoder tool I created<\/a>.<\/li>\n
    2. Add an image using Markdown syntax with ![ALT text](data:image\/svg+xml,<URL-encoded string here>)<\/code>.<\/li>\n<\/ol>\n
      For any non-trivial SVG the URL-encoded string will look huge and nasty, as the image below shows:<\/p>\n
      \"Screenshot
      The URL-encoded SVG.<\/figcaption><\/figure>\n
      But when I \u201cexecute\u201d the cell to render the Markdown, the SVG displays neatly:<\/p>\n
      \"Screenshot
      The rendered SVG.<\/figcaption><\/figure>\n
      This was an interesting endeavour because I thought I could just paste the SVG markup in the notebook cell and it would be rendered; I was under the impression that you could write arbitrary HTML in those cells.\nI was either wrong or I did it in the wrong way!<\/p>","summary":"Today I learned how to inline SVGs in Jupyter notebooks in two simple steps.","date_modified":"2025-11-24T01:18:24+01:00","tags":["productivity","programming"],"image":"\/user\/pages\/02.blog\/04.til\/137.inline-svgs-in-jupyter-notebooks\/thumbnail.webp"},{"title":"TIL #136 \u2013 Publish an EPUB book with Jupyter Book","date_published":"2025-11-17T11:01:00+01:00","id":"https:\/\/mathspp.com\/blog\/til\/publish-an-epub-book-with-jupyter-book","url":"https:\/\/mathspp.com\/blog\/til\/publish-an-epub-book-with-jupyter-book","content_html":"
      Today I learned how to set the configurations of my Jupyter Book to build my book in the EPUB format.<\/p>\n\n
      Publish an EPUB book with Jupyter Book<\/a><\/h1>\n
      I've been redoing my book Pydon'ts \u2013 Write elegant Python code<\/a> in Jupyter Book<\/a> (v1) because the PDFs have great typesetting defaults and look much better than what I currently have with pandoc plus a couple of custom filters.<\/p>\n
      I was trying to also get Jupyter Book to build my book in EPUB format but was struggling a bit with it because I was getting a couple of weird warnings when I ran the build command:<\/p>\n
      bash % jb build --all --builder=custom --custom-builder=epub .<\/code><\/pre>\n
      This created an EPUB with the name Projectnamenotset.epub<\/code> and the book title was Projectnamenotset<\/code>, so I knew something was off.<\/p>\n
      The configuration file had the correct metadata:<\/p>\n
      # _config.yml\ntitle: Pydon'ts \u2013 Write elegant Python code\nauthor: Rodrigo Gir\u00e3o Serr\u00e3o\n# ...<\/code><\/pre>\n
      \n
      Strictly speaking, I was only getting warnings so the build process was working fine.\nBut I wanted to run the flag -W<\/code>, which turns warnings into errors, so I was hitting a couple of roadblocks on top of the weird project name.<\/p>\n<\/div>\n
      EPUB3 requires a version<\/a><\/h2>\n
      I was getting a warning saying that the format EPUB3 required a non-empty version, which just meant I had to specify a version in the Sphinx config:<\/p>\n
      sphinx:\n  config:\n    version: \"2025.11.17\"<\/code><\/pre>\n
      Setting the EPUB file name<\/a><\/h2>\n
      To set the EPUB file name to something other than Projectnamenotset.epub<\/code> I had to set the option epub_basename<\/code> in the Sphinx config:<\/p>\n
      # _config.yml\nsphinx:\n  config:\n    # ...\n    epub_basename: \"pydonts\"<\/code><\/pre>\n
      Setting the EPUB title<\/a><\/h2>\n
      Although I had the title<\/code> metadata set, I had to set it again in the Sphinx config so it would show as the EPUB title:<\/p>\n
      sphinx:\n  config:\n    # ...\n    epub_title: \"Pydon'ts \u2013 Write elegant Python code\"<\/code><\/pre>\n
      Unknown mimetype for index.html<\/code><\/a><\/h2>\n
      Since my root file is not called index<\/code>, I was also getting a warning saying sphinx.errors.SphinxWarning: unknown mimetype for index.html<\/code>.<\/p>\n
      Long story short, an extension wants me to have the file index.html<\/code> so that I can always navigate to the root URL and see something, and then the file index.html<\/code> just redirects to my custom root, which is foreword<\/code> in this case:<\/p>\n
      # _toc.yml\nformat: jb-book\nroot: foreword  # <--\nparts:\n  - caption: Introduction\n    chapters:\n    - file: pydonts\/pydont-disrespect-the-zen-of-python.md\n    # ...<\/code><\/pre>\n
      So, I had to tell the EPUB builder to ignore the file index.html<\/code>, that was being built but shouldn't be used when building the final EPUB:<\/p>\n
      sphinx:\n  config:\n    epub_exclude_files:\n      - \"index.html\"<\/code><\/pre>\n
      Final configuration<\/a><\/h2>\n
      Here's the final set of configurations I use to build the EPUB:<\/p>\n
      sphinx:\n  config:\n    epub_exclude_files:\n      - \"index.html\"\n    epub_basename: \"pydonts\"\n    epub_title: \"Pydon'ts \u2013 Write elegant Python code\"\n    version: \"2025.11.17\"\n    language: en<\/code><\/pre>\n
      I build with this command:<\/p>\n
      bash % jb build --all --builder=custom --custom-builder=epub -W .<\/code><\/pre>","summary":"Today I learned how to set the configurations of my Jupyter Book to build my book in the EPUB format.","date_modified":"2025-11-17T12:20:19+01:00","tags":["productivity"],"image":"\/user\/pages\/02.blog\/04.til\/136.publish-an-epub-book-with-jupyter-book\/thumbnail.webp"}]}