superpage 1__tar.gz

superpage-1/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2025 Klas Lindberg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

superpage-1/PKG-INFO

@@ -0,0 +1,20 @@
+Metadata-Version: 2.4
+Name: superpage
+Version: 1
+Summary: Lightweight Markdown builder
+Author-email: Klas Lindberg <flimango@protonmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Mysingen/superpage
+Project-URL: Issues, https://github.com/Mysingen/superpage/issues
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: watchdog>=6.0.0
+Requires-Dist: markdown>=3.10
+Dynamic: license-file
+
+# Superpage
+
+Superpage is a lightweight Markdown processor that offers snappy live editing,
+and human readable HTML output with very few dependencies.

superpage-1/README.md

@@ -0,0 +1,4 @@
+# Superpage
+
+Superpage is a lightweight Markdown processor that offers snappy live editing,
+and human readable HTML output with very few dependencies.

superpage-1/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "superpage"
+version = "1"
+authors = [
+  { name="Klas Lindberg", email="flimango@protonmail.com" },
+]
+description = "Lightweight Markdown builder"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+dependencies = [
+    "pyyaml>=6.0.3",
+    "watchdog>=6.0.0",
+    "markdown>=3.10",
+]
+
+[project.urls]
+Homepage = "https://github.com/Mysingen/superpage"
+Issues = "https://github.com/Mysingen/superpage/issues"
+
+[build-system]
+requires = ["setuptools>=60"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+packages = ["superpage"]
+
+[tool.setuptools.package-data]
+superpage = ["resources/*"]

superpage-1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

superpage-1/superpage/__init__.py

@@ -0,0 +1,16 @@
+import pathlib
+
+from .book import Book
+from .builder import Builder
+from .config import Config, Flags
+from .linter import LinkProblem, HtmlAnchorExtractor
+from .meta import PKG_ROOT
+from .monitor import Logger
+from .navigation import NavData
+from .page import Page
+from .event import Event, EventKind, SeverityLevel
+from .reference import Reference, ReferenceExtractor
+from .server import Server, Client, ServerObserveKind
+from .summary import Summary
+from .tasks import BuilderTask, ServerTask
+from .watcher import Watcher

superpage-1/superpage/__main__.py

@@ -0,0 +1,56 @@
+import pathlib
+import sys
+import threading
+import time
+
+# make superpage importable as package
+PKG_ROOT = pathlib.Path(__file__).parent
+sys.path.insert(0, str(PKG_ROOT.parent))
+
+for p in sys.path:
+    print('    ', p)
+
+import superpage
+
+if __name__ == '__main__':
+    if len(sys.argv) < 3:
+        print('first argument must be a command, third a config file')
+        sys.exit(1)
+    command = sys.argv[1]
+    cfg_file = pathlib.Path(sys.argv[2])
+    config = superpage.Config(cfg_file.parent)
+    flags = superpage.Flags(auto_dot_pages=True)
+
+    for o in config.from_file(cfg_file).get_events():
+        print(o)
+        if o.is_problem():
+            sys.exit(1)
+
+    if command == 'build':
+        options = sys.argv[2:]
+
+        logger = superpage.Logger(
+            filter=superpage.SeverityLevel.INFO)
+        builder = superpage.Builder(logger, flags=flags)
+
+        begin = time.time()
+        builder.recover(cfg_file)
+        if 'clean' in options:
+            builder.clean()
+        num_pages = builder.build()
+        end = time.time()
+        print(f'{num_pages} pages built in {end - begin} seconds')
+        sys.exit(0)
+
+    if command == 'serve':
+        queue = superpage.monitor.EventQueue()
+        logger = superpage.Logger()
+        builder = superpage.BuilderTask(cfg_file, queue, logger)
+        server = superpage.ServerTask(cfg_file, queue, logger)
+        client = superpage.Client(cfg_file, logger)
+        client.connect(timeout=5)
+        del client
+
+        server.join()
+        builder.join()
+        sys.exit(0)

superpage-1/superpage/book.py

@@ -0,0 +1,445 @@
+import os
+import pathlib
+
+from superpage.config import Config, Flags
+from superpage.linter import HtmlAnchorExtractor, SeverityLevel
+from superpage.event import Event, EventKind
+from superpage.monitor import Logger
+from superpage.navigation import DotPages, is_link_loop
+from superpage.page import Page
+from superpage.summary import Summary
+
+def all_files(
+        path : pathlib.Path
+        ) -> list [ pathlib.Path ]:
+    return [p for p in sorted(path.rglob('*')) if not is_link_loop(p)]
+
+def all_md_files(
+        path : pathlib.Path
+        ) -> list [ pathlib.Path ]:
+    return [p for p in sorted(path.rglob('*.md')) if not is_link_loop(p)]
+
+def all_html_files(
+        path : pathlib.Path
+        ) -> list [ pathlib.Path ]:
+    return [p for p in sorted(path.rglob('*.html')) if not is_link_loop(p)]
+
+class Book:
+    flags : Flags
+    root_dir : pathlib.Path
+    config : Config
+    logger : Logger
+    path : pathlib.Path
+    title : str
+    _pages : list [ Page ] # all book pages. shares objects with dot_pages
+    dot_pages : DotPages # subset of all pages known for the book
+    site_path : pathlib.Path
+
+    def __init__(
+            self,
+            root_dir : pathlib.Path,
+            config : Config,
+            logger : Logger,
+            path : pathlib.Path,
+            title : str,
+            *,
+            flags : Flags
+            ):
+        self.flags = flags
+        assert(root_dir.is_absolute())
+        assert(path.is_absolute())
+        self.root_dir = root_dir
+        self.config = config
+        self.logger = logger
+        self.path = path
+        self._pages = []
+        self.title = title
+        self.dot_pages = None
+
+        self.site_path = None
+        if self.config.site_dir:
+            rel_site_path = self.path.relative_to(self.root_dir)
+            self.site_path = self.config.site_dir / rel_site_path
+
+    def from_dot_pages(
+            self
+            ):
+
+        path = self.path / '.pages'
+        dp = DotPages(
+            self.root_dir,
+            self.config,
+            self.logger,
+            flags=self.flags)
+
+        if not path.exists():
+            # must have the class member instantiated to build at all but not
+            # obliged to also save it to disk:
+            self.dot_pages = None # if we're in recovery after deleting the file
+            if self.flags.auto_dot_pages:
+                self.logger.put(Event(
+                    SeverityLevel.INFO,
+                    path, None,
+                    'automatically creating .pages file',
+                    EventKind.AUTO_ADD_DOT_PAGES))
+                dp.to_file(path)
+
+        if self.dot_pages:
+            self.dot_pages.update_from_file(path, table=self.dot_pages)
+        else:
+            self.dot_pages = dp
+            dp.from_file(path, table=self.dot_pages)
+
+    def clean(
+            self
+            ):
+        files = all_html_files(self.site_path)
+    
+        for f in files:
+            self.logger.put(Event(
+                SeverityLevel.INFO,
+                pathlib.PurePosixPath(f), None,
+                '-',
+                EventKind.CLEAN_OUTPUT))
+            os.unlink(f)
+
+    def add_page(
+            self,
+            page : Page
+            ) -> None:
+        if page not in self._pages:
+            self._pages.append(page)
+            return True
+        return False
+
+    def remove_page(
+            self,
+            page : Page
+            ) -> None:
+        if page not in self._pages:
+            return
+        self._pages.remove(page)
+
+    def patch_dot_pages(
+            self,
+            path : pathlib.Path,
+            *,
+            table : DotPages
+            ) -> Page:
+        self.logger.put(Event(
+            SeverityLevel.WARNING,
+            path, self.path / '.pages',
+            f'source file is not mentioned',
+            EventKind.NO_DOT_PAGES_MENTION))
+
+        entry = None
+
+        # add orphan .md and .pages files to the book's nav tree:
+        if path.suffix == '.md':
+            entry = Page(self.root_dir, self.config, self.logger, path)
+            title = entry.guess_title()
+            self.dot_pages.add_page(title, entry, auto_added=True)
+
+        elif path.name == '.pages':
+            # need an awkward default for the title but can make something from
+            # the book's title and the file path:
+            rel_dir_path = path.relative_to(self.root_dir).parent
+            title = ' / '.join([p for p in rel_dir_path.parts])
+            entry = DotPages(
+                self.root_dir, self.config, self.logger, flags=self.flags)
+            entry.from_file(path, table=table)
+            self.dot_pages.add_dot_pages(title, entry)
+
+        else:
+            assert(False and 'unreachable code')
+
+        if self.flags.auto_dot_pages:
+            # also save the root .pages file under the auto flag
+            self.logger.put(Event(
+                SeverityLevel.INFO,
+                path, self.path / '.pages',
+                f'source file added automatically',
+                EventKind.AUTO_ADD_DOT_PAGES))
+            self.dot_pages.to_file(self.dot_pages.path)
+
+        return entry
+
+    def build_page(
+            self,
+            md_path : pathlib.Path,
+            *,
+            table : DotPages
+            ):
+        assert(md_path.is_absolute())
+
+        # the same source file may be mentioned multiple times in a .pages
+        # file so we can get more than one page back:
+        page_list = self.dot_pages.get_pages(md_path)
+
+        # the page is not referenced by any .pages that is reachable through
+        # the root .pages file, or there is no root .pages file at all:
+        if not page_list:
+            page_list.append(
+                self.patch_dot_pages(md_path, table=table))
+
+        for page in page_list:
+            self.add_page(page) # in case we never saw it before
+            # this is not the time or place to worry about build avoidance. just
+            # call build() on the same content multiple times.
+            page.build()
+
+    def recover_page(
+            self,
+            path : pathlib.Path,
+            *,
+            table : DotPages
+            ):
+        assert(path.is_absolute())
+
+        # the same source file may be mentioned multiple times in a .pages
+        # file so we can get more than one page back:
+        page_list = self.dot_pages.get_pages(path)
+
+        # the page is not referenced by any .pages that is reachable through
+        # the root .pages file, or there is no root .pages file at all:
+        if not page_list:
+            page_list.append(
+                self.patch_dot_pages(path, table=table))
+
+        for page in page_list:
+            self.add_page(page) # in case we never saw it before
+            page.recover()
+
+    def remove_any(
+            self,
+            path : pathlib.Path
+            ):
+        assert(path.is_absolute())
+
+        entry_list = self.dot_pages.remove_any(path)
+        do_recovery = False
+
+        for e in entry_list:
+
+            if type(e.reference) == Page:
+                self.remove_page(e.reference)
+                html = path.with_suffix('.html')
+                if not html.exists():
+                    return
+                self.logger.put(Event(
+                    SeverityLevel.INFO,
+                    pathlib.PurePosixPath(html), None,
+                    '-',
+                    EventKind.CLEAN_OUTPUT))
+                os.unlink(html)
+
+            if type(e.reference) == DotPages:
+                do_recovery = True
+
+        if path == self.dot_pages.path:
+            do_recovery = True
+
+        if do_recovery:
+            self.dot_pages = None
+            self.recover()
+
+    def move_any(
+            self,
+            src : pathlib.Path,
+            dst : pathlib.Path,
+            *,
+            table : DotPages
+            ) -> None:
+        assert(src.is_absolute())
+        assert(dst.is_absolute())
+
+        entry_list = self.dot_pages.remove_any(src)
+        do_recovery = False
+
+        for e in entry_list:
+
+            if type(e.reference) == Page:
+                self.remove_page(e.reference)
+                html = src.with_suffix('.html')
+                self.logger.put(Event(
+                    SeverityLevel.INFO,
+                    pathlib.PurePosixPath(html), None,
+                    '-',
+                    EventKind.CLEAN_OUTPUT))
+                if html.is_file():
+                    os.unlink(html)
+                self.build_page(dst, table=self.dot_pages)
+                do_recovery = True
+
+            if type(e.reference) == DotPages:
+                do_recovery = True
+
+        if src == self.dot_pages.path or dst == self.dot_pages.path:
+            do_recovery = True
+
+        if do_recovery:
+            self.dot_pages = None
+            self.recover()
+
+    def build_nav(
+            self,
+            dot_pages_path : pathlib.Path
+            ):
+        # overall strategy:
+        # reorder Page and DotPages objects within the existing DotPages object
+        # based on the order they are seen in the changed .pages file. reorder
+        # Page objects within the existing Page list based on the order they are
+        # seen in the updated DotPages tree.
+
+        assert(self.dot_pages) # books at least always have fake .pages assigned
+
+        dps = self.dot_pages.get_dot_pages(dot_pages_path)
+        if dot_pages_path == self.dot_pages.path:
+            # the root .pages file should not have aliases in the navigation
+            # data since it is not referenced by any other .pages file and must
+            # not reference itself:
+            assert(len(dps) == 1)
+
+        # pass in a table of all existing entries to not recreate entries that
+        # have already been built before:
+        table = self.dot_pages
+        dps[0].update_from_file(dot_pages_path, table)
+
+        # update the book's flat page list ordering and build reachable pages
+        updated : list [ Page ] = []
+        rebuilt : list [ Page ] = []
+        old_paths = [p.path for p in self._pages]
+        for d in dps:
+            for p in d.list_pages(recursive=True) or []:
+                try:
+                    i = old_paths.index(p.path)
+                    updated.append(self._pages[i])
+                except ValueError:
+                    updated.append(p)
+                    rebuilt.append(p)
+                p.build() # do build avoidance in there, not here
+
+        self._pages = updated
+
+    def build(
+            self
+            ) -> int:
+        assert(self.path.is_absolute())
+
+        # dilemma: .md files may not be listed in .pages and .pages may contain
+        # entries that do not have any .md backing. need to find both problems.
+        # DotPages.from_file() checks existence of files referenced in .pages
+        # files. here we build *all* md in the project and log a problem for any
+        # file not mentioned in a .pages entry.
+
+        md_files = all_md_files(self.path)
+        for f in md_files:
+            self.build_page(self.path / f, table=self.dot_pages)
+
+        return len(md_files)
+
+    def recover(
+            self
+            ) -> int:
+        assert(self.path.is_absolute())
+
+        # this will discover all, none or some of the book's .pages files:
+        self.from_dot_pages()
+
+        md_files = 0
+
+        for f in all_files(self.path):
+            p = self.path / f
+            if p.suffix == '.md':
+                # sets title=None but the next file could be a .pages that sets
+                # the title. order of discovery is awkward...
+                self.recover_page(p, table=self.dot_pages)
+                md_files += 1
+            elif p.name == '.pages':
+                # check that this .pages was not discovered in from_dot_pages()
+                if not self.dot_pages.get_dot_pages(p):
+                    self.patch_dot_pages(p, table=self.dot_pages)
+
+        return md_files
+
+    def summarize(
+            self
+            ) -> Summary:
+        summary = self.dot_pages.summarize()
+        summary.all_dot_pages_count += 1 # not self-counted by the call
+        return summary
+
+    def get_page(
+            self,
+            path : pathlib.Path
+            ) -> Page:
+        assert(path.is_absolute())
+        for page in self._pages:
+            if page.path == path:
+                return page
+        return None
+
+    # a .pages file is allowed to reference the same path multiple times, in
+    # which case the returned list will hold multiple representations of the
+    # same .pages file.
+    def get_dot_pages(
+            self,
+            path : pathlib.Path
+            ) -> list [ DotPages ]:
+        assert(path.is_absolute())
+        if path == self.dot_pages.path:
+            return [self.dot_pages]
+        return self.dot_pages.get_dot_pages(path)
+
+    def lint_links(
+            self
+            ):
+        for page in self._pages:
+            for hazard in page.link_hazards:
+                # there should only be anchorage hazards to look into a
+                # second time after all pages have been translated:
+                assert hazard.is_anchorage_kind()
+                path, anchor = hazard.get_path_and_anchor()
+
+                if hazard.kind == EventKind.NO_SUCH_ANCHOR:
+                    # find the page that represents the markdown file
+                    # targeted by the link. then look inside its metadata
+                    # to check if the wanted anchor was seen during
+                    # translation.
+                    if path:
+                        assert(path.endswith('.md'))
+                        resolved = (page.path.parent / path).resolve()
+                        target = self.get_page(resolved)
+                        if not target:
+                            print(f'INTERNAL: {target} not indexed by {self.title}')
+                            continue
+                        #assert(target)
+                    else:
+                        target = page # in-page reference
+
+                    if anchor not in target.list_anchors():
+                        page.link_problems.append(hazard)
+                        self.logger.put(hazard)
+                    continue
+
+                if hazard.kind == EventKind.HTML_ANCHORAGE:
+                    # prase the target file to find anchor definitions
+                    parser = HtmlAnchorExtractor()
+                    resolved = (page.path.parent / path).resolve()
+                    with open(resolved, encoding='utf-8') as f:
+                        parser.feed(f.read())
+                        parser.close()
+                    if anchor not in parser.anchors:
+                        page.link_problems.append(hazard)
+                        self.logger.put(hazard)
+                    continue
+
+                # not checking anchor links into "too alien" file formats
+                # even though at least some of them (PDF files) should be
+                # supportable:
+                if hazard.kind == EventKind.NO_CLEAR_ANCHORAGE:
+                    page.link_problems.append(hazard)
+                    self.logger.put(hazard)
+                    continue
+
+            page.link_hazards = [] # reclaim memory