WhakerPy 0.1__tar.gz → 0.2__tar.gz

{WhakerPy-0.1 → WhakerPy-0.2}/AUTHORS

@@ -23,5 +23,5 @@ Main author, contributor, maintainer, developer:
 
 Contributors:
 
-    * 2023: Florian Lopitaux
+    * avril-june 2023: Florian Lopitaux
     * any help or constructive comment is welcome

{WhakerPy-0.1/WhakerPy.egg-info → WhakerPy-0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: WhakerPy
-Version: 0.1
+Version: 0.2
 Summary: Web HTML maker in Python - a light web application framework
 Author-email: Brigitte Bigi <develop@sppas.org>
 License:                     GNU GENERAL PUBLIC LICENSE
@@ -727,22 +727,22 @@ the GNU General Public License version 3.
 
 ### From its repo:
 
-Download the repository and unpack it or clone with `git`.
+Download the repository and unpack it, or clone with `git`.
 WhakerPy package includes the following folders and files:
 
 1. "whakerpy": the source code package
-2. "docs": the documentation of whakerpy in HTML
-3. "tests": unittest of whakerpy source code
-4. "sample": 
-5. "etc": etcetera!
+2. "doc": the documentation of whakerpy in HTML
+3. "sample": 
+4. "etc": etcetera!
 
 
-### From its package:
+### From its wheel package:
 
-Download the wheel file and install it in your python environment with:
+Download the wheel file (WhakerPy-xxx.whl) and install it in your 
+python environment with:
 
 ```bash
-> python -m pip install dist/<whakerpy.whl>
+> python -m pip install dist/<WhakerPy-xxx.whl>
 ````
 
 ### From pypi.org:
@@ -752,7 +752,6 @@ Download the wheel file and install it in your python environment with:
 ````
 
 
-
 ## Quick Start
 
 Open a Python interpreter and type or paste the following:
@@ -811,7 +810,6 @@ Let's view the result in your favorite web browser
 >>> webbrowser.open_new_tab(file_whakerpy)
 ```
 
-
 ## Create a web application frontend with dynamic HTML content
 
 For a quick start, see the file `sample.py`. It shows a very simple
@@ -826,13 +824,61 @@ For a more complex example of an already in-used web frontend, see:
 
 ## Projects using `WhakerPy `
 
-`WhakerPy` was initially developed within SPPAS <http://sppas/org>; it was 
+`WhakerPy` was initially developed within SPPAS <https://sppas.org>; it was 
 extracted from its original software by its author to lead its own life as 
 standalone package. The "setup" of SPPAS is entirely based on whakerpy API,
 and it's website too.
 
 Other projects: 
-- pages of the website "<https://auto-cuedspeech.org>" are created by whakerpy.
+- pages of the website <https://auto-cuedspeech.org> are created by whakerpy.
 - *contact the author if your project is using whakerpy*
 
 
+# The developer's corner
+
+## Create a wheel
+
+WhakerPy is no system dependent. Information to build its wheel are stored 
+into the file `pyproject.toml`. 
+
+The universal wheel is created with: `python -m build`
+
+## Make the doc
+
+The API documentation is available in the `doc` folder. Click the file `index.html`
+to browse throw the documented classes of WhakerPy.
+
+To re-generate the doc, install the required external program: 
+`python -m pip install -r doc/requirements.txt`
+Then, launch the doc generator: `cd doc; python makedoc.py`
+
+## Analyze WhakerPy code
+
+Unittests coverage can be analyzed with pytest and coverage. Install them
+with the command: `python -m pip install -r tests/requirements.txt`
+
+Then, perform the following steps:
+
+1. `coverage run -m pytest`
+2. `coverage report` to see a summary report into the terminal,
+or use this command to get the result in XML format: `coverage xml; mv coverage.xml tests`
+
+The whakerpy package can be analyzed with SonarQube by following these steps:
+
+1. Download and install Docker
+2. Download and install SonarQube: 
+   `docker pull sonarqube:latest`
+3. Start the SonarQube server by running: 
+   `docker run --stop-timeout 3600 -d --name sonarqube -p 9000:9000 sonarqube:latest`
+   Log in to http://localhost:9000. Both login and password are "admin".  
+   Add the python plugin and restart server.
+4. Click "Add project" with name "WhakerPy", and provide it a token
+5. Copy/Paste the token into the file whakerpy/sonar-project.properties
+6. Download sonar-scanner client: 
+   `brew install sonar-scanner` (or something else, it obviously depends on your OS)
+7. Launch: `sonar-scanner`
+8. See results in the opened URL, and don't forget it's an *automatic* code analyzer, not an *intelligent* one.
+
+## Contribute
+
+If you plan to contribute to the code, please send an e-mail to the author.

{WhakerPy-0.1 → WhakerPy-0.2}/README.md

@@ -32,22 +32,22 @@ the GNU General Public License version 3.
 
 ### From its repo:
 
-Download the repository and unpack it or clone with `git`.
+Download the repository and unpack it, or clone with `git`.
 WhakerPy package includes the following folders and files:
 
 1. "whakerpy": the source code package
-2. "docs": the documentation of whakerpy in HTML
-3. "tests": unittest of whakerpy source code
-4. "sample": 
-5. "etc": etcetera!
+2. "doc": the documentation of whakerpy in HTML
+3. "sample": 
+4. "etc": etcetera!
 
 
-### From its package:
+### From its wheel package:
 
-Download the wheel file and install it in your python environment with:
+Download the wheel file (WhakerPy-xxx.whl) and install it in your 
+python environment with:
 
 ```bash
-> python -m pip install dist/<whakerpy.whl>
+> python -m pip install dist/<WhakerPy-xxx.whl>
 ````
 
 ### From pypi.org:
@@ -57,7 +57,6 @@ Download the wheel file and install it in your python environment with:
 ````
 
 
-
 ## Quick Start
 
 Open a Python interpreter and type or paste the following:
@@ -116,7 +115,6 @@ Let's view the result in your favorite web browser
 >>> webbrowser.open_new_tab(file_whakerpy)
 ```
 
-
 ## Create a web application frontend with dynamic HTML content
 
 For a quick start, see the file `sample.py`. It shows a very simple
@@ -131,13 +129,61 @@ For a more complex example of an already in-used web frontend, see:
 
 ## Projects using `WhakerPy `
 
-`WhakerPy` was initially developed within SPPAS <http://sppas/org>; it was 
+`WhakerPy` was initially developed within SPPAS <https://sppas.org>; it was 
 extracted from its original software by its author to lead its own life as 
 standalone package. The "setup" of SPPAS is entirely based on whakerpy API,
 and it's website too.
 
 Other projects: 
-- pages of the website "<https://auto-cuedspeech.org>" are created by whakerpy.
+- pages of the website <https://auto-cuedspeech.org> are created by whakerpy.
 - *contact the author if your project is using whakerpy*
 
 
+# The developer's corner
+
+## Create a wheel
+
+WhakerPy is no system dependent. Information to build its wheel are stored 
+into the file `pyproject.toml`. 
+
+The universal wheel is created with: `python -m build`
+
+## Make the doc
+
+The API documentation is available in the `doc` folder. Click the file `index.html`
+to browse throw the documented classes of WhakerPy.
+
+To re-generate the doc, install the required external program: 
+`python -m pip install -r doc/requirements.txt`
+Then, launch the doc generator: `cd doc; python makedoc.py`
+
+## Analyze WhakerPy code
+
+Unittests coverage can be analyzed with pytest and coverage. Install them
+with the command: `python -m pip install -r tests/requirements.txt`
+
+Then, perform the following steps:
+
+1. `coverage run -m pytest`
+2. `coverage report` to see a summary report into the terminal,
+or use this command to get the result in XML format: `coverage xml; mv coverage.xml tests`
+
+The whakerpy package can be analyzed with SonarQube by following these steps:
+
+1. Download and install Docker
+2. Download and install SonarQube: 
+   `docker pull sonarqube:latest`
+3. Start the SonarQube server by running: 
+   `docker run --stop-timeout 3600 -d --name sonarqube -p 9000:9000 sonarqube:latest`
+   Log in to http://localhost:9000. Both login and password are "admin".  
+   Add the python plugin and restart server.
+4. Click "Add project" with name "WhakerPy", and provide it a token
+5. Copy/Paste the token into the file whakerpy/sonar-project.properties
+6. Download sonar-scanner client: 
+   `brew install sonar-scanner` (or something else, it obviously depends on your OS)
+7. Launch: `sonar-scanner`
+8. See results in the opened URL, and don't forget it's an *automatic* code analyzer, not an *intelligent* one.
+
+## Contribute
+
+If you plan to contribute to the code, please send an e-mail to the author.

{WhakerPy-0.1 → WhakerPy-0.2/WhakerPy.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: WhakerPy
-Version: 0.1
+Version: 0.2
 Summary: Web HTML maker in Python - a light web application framework
 Author-email: Brigitte Bigi <develop@sppas.org>
 License:                     GNU GENERAL PUBLIC LICENSE
@@ -727,22 +727,22 @@ the GNU General Public License version 3.
 
 ### From its repo:
 
-Download the repository and unpack it or clone with `git`.
+Download the repository and unpack it, or clone with `git`.
 WhakerPy package includes the following folders and files:
 
 1. "whakerpy": the source code package
-2. "docs": the documentation of whakerpy in HTML
-3. "tests": unittest of whakerpy source code
-4. "sample": 
-5. "etc": etcetera!
+2. "doc": the documentation of whakerpy in HTML
+3. "sample": 
+4. "etc": etcetera!
 
 
-### From its package:
+### From its wheel package:
 
-Download the wheel file and install it in your python environment with:
+Download the wheel file (WhakerPy-xxx.whl) and install it in your 
+python environment with:
 
 ```bash
-> python -m pip install dist/<whakerpy.whl>
+> python -m pip install dist/<WhakerPy-xxx.whl>
 ````
 
 ### From pypi.org:
@@ -752,7 +752,6 @@ Download the wheel file and install it in your python environment with:
 ````
 
 
-
 ## Quick Start
 
 Open a Python interpreter and type or paste the following:
@@ -811,7 +810,6 @@ Let's view the result in your favorite web browser
 >>> webbrowser.open_new_tab(file_whakerpy)
 ```
 
-
 ## Create a web application frontend with dynamic HTML content
 
 For a quick start, see the file `sample.py`. It shows a very simple
@@ -826,13 +824,61 @@ For a more complex example of an already in-used web frontend, see:
 
 ## Projects using `WhakerPy `
 
-`WhakerPy` was initially developed within SPPAS <http://sppas/org>; it was 
+`WhakerPy` was initially developed within SPPAS <https://sppas.org>; it was 
 extracted from its original software by its author to lead its own life as 
 standalone package. The "setup" of SPPAS is entirely based on whakerpy API,
 and it's website too.
 
 Other projects: 
-- pages of the website "<https://auto-cuedspeech.org>" are created by whakerpy.
+- pages of the website <https://auto-cuedspeech.org> are created by whakerpy.
 - *contact the author if your project is using whakerpy*
 
 
+# The developer's corner
+
+## Create a wheel
+
+WhakerPy is no system dependent. Information to build its wheel are stored 
+into the file `pyproject.toml`. 
+
+The universal wheel is created with: `python -m build`
+
+## Make the doc
+
+The API documentation is available in the `doc` folder. Click the file `index.html`
+to browse throw the documented classes of WhakerPy.
+
+To re-generate the doc, install the required external program: 
+`python -m pip install -r doc/requirements.txt`
+Then, launch the doc generator: `cd doc; python makedoc.py`
+
+## Analyze WhakerPy code
+
+Unittests coverage can be analyzed with pytest and coverage. Install them
+with the command: `python -m pip install -r tests/requirements.txt`
+
+Then, perform the following steps:
+
+1. `coverage run -m pytest`
+2. `coverage report` to see a summary report into the terminal,
+or use this command to get the result in XML format: `coverage xml; mv coverage.xml tests`
+
+The whakerpy package can be analyzed with SonarQube by following these steps:
+
+1. Download and install Docker
+2. Download and install SonarQube: 
+   `docker pull sonarqube:latest`
+3. Start the SonarQube server by running: 
+   `docker run --stop-timeout 3600 -d --name sonarqube -p 9000:9000 sonarqube:latest`
+   Log in to http://localhost:9000. Both login and password are "admin".  
+   Add the python plugin and restart server.
+4. Click "Add project" with name "WhakerPy", and provide it a token
+5. Copy/Paste the token into the file whakerpy/sonar-project.properties
+6. Download sonar-scanner client: 
+   `brew install sonar-scanner` (or something else, it obviously depends on your OS)
+7. Launch: `sonar-scanner`
+8. See results in the opened URL, and don't forget it's an *automatic* code analyzer, not an *intelligent* one.
+
+## Contribute
+
+If you plan to contribute to the code, please send an e-mail to the author.

WhakerPy-0.2/WhakerPy.egg-info/SOURCES.txt

@@ -0,0 +1,40 @@
+AUTHORS
+LICENSE
+README.md
+pyproject.toml
+WhakerPy.egg-info/PKG-INFO
+WhakerPy.egg-info/SOURCES.txt
+WhakerPy.egg-info/dependency_links.txt
+WhakerPy.egg-info/top_level.txt
+doc/makedoc.py
+samples/response.py
+tests/__init__.py
+tests/htmlmaker/__init__.py
+tests/htmlmaker/test_basenodes.py
+tests/htmlmaker/test_emptynodes.py
+tests/htmlmaker/test_hexc.py
+tests/htmlmaker/test_htree.py
+tests/htmlmaker/test_tagnodes.py
+tests/httpd/__init__.py
+tests/httpd/test_status.py
+whakerpy/__init__.py
+whakerpy/messages.py
+whakerpy/htmlmaker/__init__.py
+whakerpy/htmlmaker/hconsts.py
+whakerpy/htmlmaker/hexc.py
+whakerpy/htmlmaker/treeelts.py
+whakerpy/htmlmaker/treenode.py
+whakerpy/htmlmaker/basenodes/__init__.py
+whakerpy/htmlmaker/basenodes/baseelts.py
+whakerpy/htmlmaker/basenodes/basenode.py
+whakerpy/htmlmaker/emptynodes/__init__.py
+whakerpy/htmlmaker/emptynodes/emptyelts.py
+whakerpy/htmlmaker/emptynodes/emptynode.py
+whakerpy/htmlmaker/tagnodes/__init__.py
+whakerpy/htmlmaker/tagnodes/tagelts.py
+whakerpy/htmlmaker/tagnodes/tagnode.py
+whakerpy/httpd/__init__.py
+whakerpy/httpd/handler.py
+whakerpy/httpd/hresponse.py
+whakerpy/httpd/hserver.py
+whakerpy/httpd/hstatus.py

WhakerPy-0.2/doc/makedoc.py

@@ -0,0 +1,227 @@
+# makedoc.py
+# Summary: Create the documentation of WhakerPy, using Clamming library.
+# Usage: python makedoc.py
+#
+# This file is part of WhakerPy tool.
+# (C) 2023 Brigitte Bigi, Laboratoire Parole et Langage,
+# Aix-en-Provence, France.
+#
+# Use of this software is governed by the GNU Public License, version 3.
+#
+# Clamming is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Clamming is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Clamming. If not, see <http://www.gnu.org/licenses/>.
+#
+# This banner notice must not be removed.
+#
+# ---------------------------------------------------------------------------
+
+from __future__ import annotations
+import os
+import sys
+sys.path.append(os.path.dirname(os.path.dirname(__file__)))
+
+from whakerpy.htmlmaker import *
+from whakerpy.httpd import *
+try:
+    from clamming import ClamsClass
+    from clamming import ClammingClassParser
+except ImportError:
+    print("This program requires `Clamming` documentation generator.")
+    print("It can be installed with: pip install Clamming.")
+    print("See <https://pypi.org/project/Clamming/> for details.")
+    sys.exit(-1)
+
+# ----------------------------------------------------------------------------
+# Constants
+# ----------------------------------------------------------------------------
+
+HTML_TOP = """<!DOCTYPE html>
+<html>
+    <head>
+        <meta charset="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
+        <title>WhakerPy Doc</title>
+        <link rel="logo icon" href="../etc/whakerpy32x32.ico" />
+        <link rel="stylesheet" href="../etc/colors_light.css" type="text/css" />
+        <link rel="stylesheet" href="../etc/main.css" type="text/css" />
+        <link rel="stylesheet" href="../etc/main_sppas.css" type="text/css" />
+        <link rel="stylesheet" href="../etc/code.css" type="text/css" />
+        <link rel="stylesheet" href="../etc/cards.css" type="text/css" />
+        <script src="../etc/toc.js" type="text/javascript"></script>
+   </head>
+<body class="light">
+     <header></header>
+     <nav id="nav-book" class="side-nav">
+         <p><strong>WhakerPy doc</strong></p>
+         <ul>
+             <li class="center">
+                 <a class="width-three-quarters" role="button" tabindex="0" {prev}> &uarr; Prev. Class</a>
+             </li>
+             <li class="center">
+                 <a class="width-three-quarters" role="button" tabindex="0" href="index.html">&#8962; Doc Home</a></li>
+             <li class="center">
+                 <a class="width-three-quarters" role="button" tabindex="0" {next}> &darr; Next Class</a>
+             </li>
+         </ul>
+     
+         <p><strong>Table of Contents</strong></p>
+         <ul id="toc"></ul>
+     
+     </nav>
+     <main id="toc-content">
+
+        <h1>
+            <img class="center small-logo" src="../etc/whakerpy.png" alt="WhakerPy logo">
+            <img class="center small-logo" src="../etc/whakerpy.png" alt="WhakerPy logo">
+            <img class="center small-logo" src="../etc/whakerpy.png" alt="WhakerPy logo">
+            <p class="center">WhakerPy tool documentation</p>
+        </h1>
+
+"""
+
+HTML_BOTTOM = """
+    </main>
+    <footer>
+        <p class="copyright"> Copyright (C) Brigitte Bigi - LPL 2023 </p>
+    </footer>
+    
+    <script>
+        document.addEventListener('DOMContentLoaded', function() {
+                 htmlTableOfContents();
+             }
+         );
+    
+         try {
+             module.exports = htmlTableOfContents;
+         } catch (e) {
+             // module.exports is not defined
+         }
+    </script>
+    <script src="../etc/accordion.js" type="text/javascript"></script>
+ </body>
+</html>
+
+"""
+
+# ---------------------------------------------------------------------------
+# Useful function to export a class into a valid HTML file.
+# ---------------------------------------------------------------------------
+
+
+def html_top(prev_link: str | None, next_link: str | None) -> str:
+    """Return the custom top part of the html output file.
+
+    """
+    if prev_link is None:
+        aprev = 'aria-disabled="true"'
+    else:
+        aprev = 'href="{:s}"'.format(prev_link)
+    if next_link is None:
+        anext = 'aria-disabled="true"'
+    else:
+        anext = 'href="{:s}"'.format(next_link)
+    return HTML_TOP.format(prev=aprev, next=anext)
+
+# ---------------------------------------------------------------------------
+
+
+def html_index_page(pages: dict) -> None:
+    """Write the index.html file from the given pages.
+
+    """
+    with open(os.path.join("", "index.html"), "w") as fp:
+        fp.write(html_top(prev_link=None, next_link=None))
+
+        for package in pages:
+            fp.write('<section id="{:s}">\n'.format(package))
+            fp.write("<h2>WhakerPy.{:s} classes</h2>\n".format(package))
+
+            fp.write('<section class="cards-panel">\n')
+            for i in range(len(pages[package])):
+                obj, page = pages[package][i]
+                fp.write('    <article class="card">\n')
+                fp.write('        <header><span>{:d}</span></header>'.format(i+1))
+                fp.write('        <main>')
+                fp.write('            <h3>{:s}</h3>'.format(obj.__name__))
+                fp.write('        </main>')
+                fp.write('        <footer>')
+                fp.write(_add_link("Read me →", page))
+                fp.write('        </footer>')
+                fp.write('    </article>')
+
+            fp.write("</section>\n")
+
+        fp.write(HTML_BOTTOM)
+
+
+def _add_link(name: str, page: str) -> str:
+    return '            <a role="button" href="{:s}">{:s}</a>'.format(page, name)
+
+# ---------------------------------------------------------------------------
+
+
+def obj_to_html(obj, out_html, prev_page=None, next_page=None) -> None:
+    """Return the custom documentation html output file of the given object.
+
+    :param obj: (Any) A python class object
+    :param out_html: (str) Output filename
+    :param prev_page: (str|None) Previous page name
+    :param next_page: (str|None) Previous page name
+
+    """
+    # Parse the object and store collected information = clamming
+    clamming = ClammingClassParser(obj)
+
+    # Export the collected clams to html
+    clams = ClamsClass(clamming)
+    html_content = clams.html()
+    with open(out_html, "w") as fp:
+        fp.write(html_top(prev_page, next_page))
+        fp.write(html_content)
+        fp.write(HTML_BOTTOM)
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+
+if __name__ == "__main__":
+    # List of HTML pages dynamically created by Clamming
+    pack1 = [
+        (BaseNode, "basenode.html"),
+        (EmptyNode, "emptynode.html"),
+        (HTMLNode, "node.html"),
+        (HTMLTree, "tree.html")
+        ]
+    pack2 = [
+        (sppasHTTPDHandler, "handler.html"),
+        (sppasBaseHTTPDServer, "server.html"),
+        (BaseResponseRecipe, "response.html")
+    ]
+    pages = {
+        "htmlmaker": pack1,
+        "httpd": pack2
+    }
+
+    # Create the index.html page. It's a table of content.
+    html_index_page(pages)
+
+    # HTML export of all documented classes.
+    for pack in pages:
+        for i in range(len(pages[pack])):
+            obj, page = pages[pack][i]
+            p = None if i == 0 else pages[pack][i-1][1]
+            n = None if i+1 == len(pages[pack]) else pages[pack][i+1][1]
+            print("{:s}".format(page))
+            obj_to_html(obj, page, prev_page=p, next_page=n)
+

{WhakerPy-0.1 → WhakerPy-0.2}/pyproject.toml

@@ -6,7 +6,7 @@
 
 [project]
 name = "WhakerPy"
-version = "0.1"
+version = "0.2"
 authors = [
   { name="Brigitte Bigi", email="develop@sppas.org" },
 ]
@@ -32,5 +32,10 @@ classifiers = [
 [build-system]
 requires = ["setuptools"]
 
+#[tool.setuptools.packages.find]
+#where = ["."]
+
 [tool.setuptools]
 packages = ["whakerpy"]
+
+