typerconf 1.0__py3-none-any.whl

typerconf/.gitignore

@@ -0,0 +1,4 @@
+__init__.py
+init.tex
+test.py
+

typerconf/Makefile

@@ -0,0 +1,18 @@
+MODULES+=	__init__.py
+
+.PHONY: all
+all: ${MODULES}
+
+.INTERMEDIATE: init.py
+__init__.py: init.py
+	${MV} $< $@
+
+
+.PHONY: clean
+clean:
+	${RM} -R ${MODULES} __pycache__
+	${RM} *.tex
+
+
+INCLUDE_MAKEFILES=../../../../makefiles
+include ${INCLUDE_MAKEFILES}/noweb.mk

typerconf/__init__.py

@@ -0,0 +1,217 @@
+"""The typerconf module and config subcommand"""
+
+import appdirs
+import json
+import logging
+import os
+import sys
+import typer
+import typing
+
+dirs = appdirs.AppDirs(sys.argv[0])
+
+class Config:
+  """Navigates nested JSON structures by dot-separated addressing."""
+
+  def __init__(self, json_data={}):
+    """
+    Constructs a config object to navigate from JSON data `json_data`.
+    """
+    self.__data = json_data
+
+  def get(self, path: str = "") -> typing.Any:
+    """
+    Returns object at `path`.
+    Example:
+    - `path = "courses.datintro22.url"` and
+    - Config contains `{"courses": {"datintro22": {"url": "https://..."}}}` 
+      will return "https://...".
+
+    Any part of the path that can be converted to an integer, will be converted 
+    to an integer. This way we can access elements of lists too.
+    """
+    structure = self.__data
+
+    if not path:
+      return structure
+
+    for part in path.split("."):
+      try:
+        part = int(part)
+      except ValueError:
+        pass
+
+      try:
+        structure = structure[part]
+      except KeyError:
+        raise KeyError(f"{part} along {path} doesn't exist")
+
+    return structure
+
+  def set(self, path: str, value: typing.Any):
+    """
+    Sets `value` at `path`. Any parts along the path that don't exist will be 
+    created.
+
+    Example:
+    - `value = "https://..."`,
+    - `path = "courses.datintro22.url"`
+    will create `{"courses": {"datintro22": {"url": "https://..."}}}`.
+
+    Any part of the path that can be converted to an integer, will be converted 
+    to an integer. This way we can access elements of lists too. However, we 
+    cannot create index 3 in a list if it doesn't exist.
+    """
+    structure = self.__data
+
+    parts = path.split(".")
+    for part in parts[:-1]:
+      try:
+        part = int(part)
+      except ValueError:
+        pass
+
+      try:
+        structure = structure[part]
+      except KeyError:
+        structure[part] = {}
+        structure = structure[part]
+
+    part = parts[-1]
+    try:
+      part = int(part)
+    except ValueError:
+      pass
+    structure[part] = value
+
+  def paths(self, from_root=""):
+    """
+    Returns all existing paths.
+
+    The optional argument `from_root` is a path and the method return all 
+    subpaths rooted at that point.
+    """
+    paths = []
+    root = self.get(from_root)
+
+    if isinstance(root, dict):
+      for part in root:
+        if from_root:
+          path = f"{from_root}.{part}"
+        else:
+          path = part
+
+        paths.append(path)
+        paths += self.paths(from_root=path)
+    elif isinstance(root, list):
+      paths += [f"{from_root}.{x}" for x in range(len(root))]
+
+    return paths
+def add_config_cmd(cli: typer.Typer):
+  """
+  Add config command to Typer cli
+  """
+  path_arg = typer.Argument(...,
+                            help="Path in config, e.g. 'courses.datintro22'. "
+                                 "Empty string is root of config.",
+                            autocompletion=complete_path)
+  value_arg = typer.Option([], "-s", "--set",
+                           help="Values to store. "
+                                "More than one value makes a list. "
+                                "Values are treated as JSON if possible.")
+
+  @cli.command(name="config")
+  def config_cmd(path: str = path_arg,
+                 values: typing.List[str] = value_arg):
+    """
+    Reads values from or writes values to the config.
+    """
+    if values:
+      set(path, values)
+    else:
+      print_config(get(path), path)
+def get(path: str = "") -> typing.Any:
+  """
+  Returns the value stored at `path` in the config.
+
+  By default, `path = ""`, which returns the entire configuration as a Config 
+  object.
+  """
+  conf = read_config()
+  return conf.get(path)
+
+def set(path: str, values: typing.List[typing.Any]):
+  """
+  Sets `value` at `path` in the config. `value` will be interpreted as JSON, if 
+  conversion to JSON fails, it will be used as is.
+  """
+  conf = read_config()
+  for i in range(len(values)):
+    try:
+      values[i] = json.loads(values[i])
+    except json.decoder.JSONDecodeError:
+      pass
+
+  if len(values) == 1:
+    values = values[0]
+
+  conf.set(path, values)
+  write_config(conf)
+def read_config(conf_path=f"{dirs.user_config_dir}/config.json"):
+  """
+  Returns the config data structure (JSON).
+  `conf_path` is an optional argument providing the path to the config file.
+  """
+  try:
+    with open(conf_path) as conf_file:
+      return Config(json.load(conf_file))
+  except FileNotFoundError:
+    logging.warning(f"Config file {conf_path} could not be found.")
+  except json.decoder.JSONDecodeError as err:
+    logging.warning(f"Config file {conf_path} could not be decoded: {err}")
+
+  return Config()
+
+def write_config(conf,
+                 conf_path=f"{dirs.user_config_dir}/config.json"):
+  """
+  Stores the config data `conf` (extracts JSON) in the config file.
+  `conf_path` is an optional argument providing the path to the config file.
+  """
+  conf_dir = os.path.dirname(conf_path)
+  if not os.path.isdir(conf_dir):
+    os.mkdir(conf_dir)
+
+  with open(conf_path, "w") as conf_file:
+    json.dump(conf.get(), conf_file)
+def complete_path(initial_path: str, conf: Config = None):
+  """
+  Returns all valid paths in the config starting with `initial_path`.
+  If `conf` is not None, use that instead of the actual config.
+  """
+  if not conf:
+    conf = Config(get())
+
+  return list(filter(lambda x: x.startswith(initial_path),
+                     conf.paths()))
+def print_config(conf, path=""):
+  """
+  Prints the config tree contained in `conf` to stdout.
+  Optional `path` is prepended.
+  """
+  try:
+    for key in conf.keys():
+      if path:
+        print_config(conf[key], f"{path}.{key}")
+      else:
+        print_config(conf[key], key)
+  except AttributeError:
+    print(f"{path} = {conf}")
+
+def main():
+  cli = typer.Typer()
+  add_config_cmd(cli)
+  cli()
+
+if __name__ == "__main__":
+  main()

typerconf/init.nw

@@ -0,0 +1,442 @@
+\section{Code outline}\label{configmodule}
+
+The base structure is standard.
+<<init.py>>=
+"""The typerconf module and config subcommand"""
+
+import appdirs
+import json
+import logging
+import os
+import sys
+import typer
+import typing
+
+<<set up appdirs dirs>>
+
+<<classes>>
+<<helper functions>>
+
+def main():
+  <<main body>>
+
+if __name__ == "__main__":
+  main()
+@
+
+\subsection{Not using [[add_typer]]}
+
+With the design outlined in \cref{Overview}, we can't use the default way of 
+Typer ([[.add_typer]]), as that would require another level of subcommands:
+\begin{minted}{bash}
+  nytid config get courses.datintro22.schedule.url
+\end{minted}
+to read out the value, but we don't want that [[get]] part in there.
+
+To work around that we need the [[cli]] object from the parent module here.
+Thus, instead of that module doing something like
+\begin{minted}{python}
+import typerconf as config
+# ...
+cli.add_typer(config.cli, name="config")
+\end{minted}
+as is normally done with Typer, that module will actually have to do
+\begin{minted}{python}
+import typerconf as config
+# ...
+config.add_config_cmd(cli)
+\end{minted}
+So we need to provide such a function.
+<<helper functions>>=
+def add_config_cmd(cli: typer.Typer):
+  """
+  Add config command to Typer cli
+  """
+  <<config subcommands>>
+@
+
+To make this module runnable on its own (using [[main]]), we will create a 
+[[cli]] object in the [[main]] function, then add the config command and 
+finally run it.
+(This is exactly how a program would add the [[config]] subcommand.)
+<<main body>>=
+cli = typer.Typer()
+add_config_cmd(cli)
+cli()
+@
+
+\subsection{Testing}
+
+We also want to test all functions we provide in this module.
+These test functions are all prepended [[test_]] to the function name.
+We will run them using [[pytest]].
+<<test init.py>>=
+from typerconf import *
+
+<<test functions>>
+@
+
+
+\section{Application directories}
+
+We use the application directory locations as provided by the [[appdirs]] 
+package.
+We automated the step with the application name by using the value of the 
+command run, \ie~[[sys.argv[0]]].
+(However, this default can be updated by just replacing the value of [[dirs]].)
+<<set up appdirs dirs>>=
+dirs = appdirs.AppDirs(sys.argv[0])
+@
+
+
+\section{Accessing the configuration: the [[get]] and [[set]] functions}
+
+We will provide two functions, [[get]] and [[set]], that modifies the config, 
+immediately syncing to the file system.
+This is the API to be used by any part of a program using this module to manage 
+the configuration.
+<<helper functions>>=
+def get(path: str = "") -> typing.Any:
+  """
+  Returns the value stored at `path` in the config.
+
+  By default, `path = ""`, which returns the entire configuration as a Config 
+  object.
+  """
+  <<read config from file>>
+  <<return the value at path in config>>
+
+def set(path: str, values: typing.List[typing.Any]):
+  """
+  Sets `value` at `path` in the config. `value` will be interpreted as JSON, if 
+  conversion to JSON fails, it will be used as is.
+  """
+  <<read config from file>>
+  <<set the value at path in config>>
+  <<write config back to file>>
+@
+
+Let's start with reading and writing the config file.
+<<read config from file>>=
+conf = read_config()
+<<write config back to file>>=
+write_config(conf)
+@ We'll see these functions in \cref{ConfigFile}.
+
+Now that we have the config structure in [[conf]] we can use it.
+Let's start with getting a value.
+<<return the value at path in config>>=
+return conf.get(path)
+@
+
+Now, to set a value, we have several cases.
+If the user supplied more than one value, we want a list.
+If only one value, we don't want to store a list with only one value in it.
+Also, we want to try interpret any value as JSON.
+If that fails, we'll use the value as-is.
+<<set the value at path in config>>=
+for i in range(len(values)):
+  try:
+    values[i] = json.loads(values[i])
+  except json.decoder.JSONDecodeError:
+    pass
+
+if len(values) == 1:
+  values = values[0]
+
+conf.set(path, values)
+@
+
+Now let's cover [[read_config]], [[write_config]], [[set_path]] and 
+[[get_path]] below.
+
+
+\section{Reading and writing the config file}\label{ConfigFile}
+
+The configuration file is stored in a suitable system location.
+For this we use the AppDirs package, we have the [[dirs]] instance above.
+We want to read the config and return a JSON structure as outlined above 
+(\cref{ConfigStructure}).
+And conversely, write one to the config file as well.
+<<helper functions>>=
+def read_config(conf_path=f"{dirs.user_config_dir}/config.json"):
+  """
+  Returns the config data structure (JSON).
+  `conf_path` is an optional argument providing the path to the config file.
+  """
+  try:
+    with open(conf_path) as conf_file:
+      return Config(json.load(conf_file))
+  except FileNotFoundError:
+    logging.warning(f"Config file {conf_path} could not be found.")
+  except json.decoder.JSONDecodeError as err:
+    logging.warning(f"Config file {conf_path} could not be decoded: {err}")
+
+  return Config()
+
+def write_config(conf,
+                 conf_path=f"{dirs.user_config_dir}/config.json"):
+  """
+  Stores the config data `conf` (extracts JSON) in the config file.
+  `conf_path` is an optional argument providing the path to the config file.
+  """
+  conf_dir = os.path.dirname(conf_path)
+  if not os.path.isdir(conf_dir):
+    os.mkdir(conf_dir)
+
+  with open(conf_path, "w") as conf_file:
+    json.dump(conf.get(), conf_file)
+@
+
+
+\section{Navigating config structures}\label{ConfigClass}
+
+We provide the class [[Config]] to navigate the config structure.
+This class has two methods that are central:
+The first gets a value out, the other sets a value in.
+Both work with these dot-separated addresses.
+<<classes>>=
+class Config:
+  """Navigates nested JSON structures by dot-separated addressing."""
+
+  def __init__(self, json_data={}):
+    """
+    Constructs a config object to navigate from JSON data `json_data`.
+    """
+    self.__data = json_data
+
+  def get(self, path: str = "") -> typing.Any:
+    """
+    Returns object at `path`.
+    Example:
+    - `path = "courses.datintro22.url"` and
+    - Config contains `{"courses": {"datintro22": {"url": "https://..."}}}` 
+      will return "https://...".
+
+    Any part of the path that can be converted to an integer, will be converted 
+    to an integer. This way we can access elements of lists too.
+    """
+    <<get value at path>>
+
+  def set(self, path: str, value: typing.Any):
+    """
+    Sets `value` at `path`. Any parts along the path that don't exist will be 
+    created.
+
+    Example:
+    - `value = "https://..."`,
+    - `path = "courses.datintro22.url"`
+    will create `{"courses": {"datintro22": {"url": "https://..."}}}`.
+
+    Any part of the path that can be converted to an integer, will be converted 
+    to an integer. This way we can access elements of lists too. However, we 
+    cannot create index 3 in a list if it doesn't exist.
+    """
+    <<set value at path>>
+
+  def paths(self, from_root=""):
+    """
+    Returns all existing paths.
+
+    The optional argument `from_root` is a path and the method return all 
+    subpaths rooted at that point.
+    """
+    <<return list of all paths>>
+@
+
+We test these methods with the examples from the docstrings.
+<<test functions>>=
+conf = Config({
+  "courses": {
+    "datintro22": {
+      "url": "https://...",
+      "TAs": ["Asse", "Assa"]
+    }
+  }
+})
+
+def test_get_path():
+  assert conf.get("courses.datintro22.url") == "https://..."
+  assert conf.get("courses.datintro22.TAs.0") == "Asse"
+
+def test_set_path():
+  value = "Asselina"
+  path = "courses.datintro22.TAs.0"
+  conf.set(path, value)
+  assert conf.get(path) == value
+
+  value = ["Asse", "Assa", "Asselina"]
+  path = "courses.prgx22.TAs"
+  conf.set(path, value)
+  assert len(conf.get(path)) == len(value)
+
+def test_paths():
+  assert "courses.datintro22.TAs" in conf.paths()
+  for path in conf.paths():
+    assert conf.get(path)
+@
+
+\subsection{Getting values}
+
+To get the value, we simply walk along the path and returns what remains.
+<<get value at path>>=
+structure = self.__data
+
+if not path:
+  return structure
+
+for part in path.split("."):
+  try:
+    part = int(part)
+  except ValueError:
+    pass
+
+  try:
+    structure = structure[part]
+  except KeyError:
+    raise KeyError(f"{part} along {path} doesn't exist")
+
+return structure
+@
+
+\subsection{Setting values}
+
+To set a value is a bit more complex.
+We want to be able to specify a path and create all parents along the path if 
+they don't exist.
+<<set value at path>>=
+structure = self.__data
+
+parts = path.split(".")
+for part in parts[:-1]:
+  try:
+    part = int(part)
+  except ValueError:
+    pass
+
+  try:
+    structure = structure[part]
+  except KeyError:
+    structure[part] = {}
+    structure = structure[part]
+
+part = parts[-1]
+try:
+  part = int(part)
+except ValueError:
+  pass
+structure[part] = value
+@
+
+\subsection{All existing paths}
+
+Lastly, what we want to do is to create a list containing all paths in the 
+config.
+We will simply traverse the config tree and add paths as we go.
+We need to treat dictionaries and lists differently.
+And anything else is a leaf.
+<<return list of all paths>>=
+paths = []
+root = self.get(from_root)
+
+if isinstance(root, dict):
+  for part in root:
+    if from_root:
+      path = f"{from_root}.{part}"
+    else:
+      path = part
+
+    paths.append(path)
+    paths += self.paths(from_root=path)
+elif isinstance(root, list):
+  paths += [f"{from_root}.{x}" for x in range(len(root))]
+
+return paths
+@
+
+
+\section{The [[config]] command}
+
+We will provide the [[config]] command as outlined above.
+If it gets a value, it will set it as the value at path.
+Otherwise, it will print the current value at path.
+<<config subcommands>>=
+path_arg = typer.Argument(...,
+                          help="Path in config, e.g. 'courses.datintro22'. "
+                               "Empty string is root of config.",
+                          autocompletion=complete_path)
+value_arg = typer.Option([], "-s", "--set",
+                         help="Values to store. "
+                              "More than one value makes a list. "
+                              "Values are treated as JSON if possible.")
+
+@cli.command(name="config")
+def config_cmd(path: str = path_arg,
+               values: typing.List[str] = value_arg):
+  """
+  Reads values from or writes values to the config.
+  """
+  if values:
+    set(path, values)
+  else:
+    print_config(get(path), path)
+@
+
+\subsection{Autocompleting the path}
+
+The [[complete_path]] functions returns the possible completions for an 
+incomplete path from the command line.
+<<helper functions>>=
+def complete_path(initial_path: str, conf: Config = None):
+  """
+  Returns all valid paths in the config starting with `initial_path`.
+  If `conf` is not None, use that instead of the actual config.
+  """
+  if not conf:
+    conf = Config(get())
+
+  return list(filter(lambda x: x.startswith(initial_path),
+                     conf.paths()))
+@
+
+We test this function as follows.
+<<test functions>>=
+def test_complete_path():
+  conf = Config({
+    "courses": {
+      "datintro22": {
+        "url": "https://...",
+        "TAs": ["Asse", "Assa"]
+      }
+    }
+  })
+
+  incomplete = "courses.datintro22.T"
+  assert "courses.datintro22.TAs" in complete_path(incomplete, conf)
+  assert "courses.datintro22.url" not in complete_path(incomplete, conf)
+  assert len(complete_path(incomplete, conf)) >= 0
+@
+
+\subsection{Printing the config}
+
+That [[print_config]] function should print the remaining levels of the config 
+tree.
+And we want it to print on the format of
+[[courses.datintro22.url = https://...]].
+This function will do a depth-first traversal through the config to print all 
+values.
+<<helper functions>>=
+def print_config(conf, path=""):
+  """
+  Prints the config tree contained in `conf` to stdout.
+  Optional `path` is prepended.
+  """
+  try:
+    for key in conf.keys():
+      if path:
+        print_config(conf[key], f"{path}.{key}")
+      else:
+        print_config(conf[key], key)
+  except AttributeError:
+    print(f"{path} = {conf}")
+@

typerconf-1.0.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022--2023 Daniel Bosk
+
+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.

typerconf-1.0.dist-info/METADATA

@@ -0,0 +1,90 @@
+Metadata-Version: 2.1
+Name: typerconf
+Version: 1.0
+Summary: Library to read and write configs using API and CLI with Typer
+Home-page: https://github.com/dbosk/typerconf
+License: MIT
+Keywords: typer,conf,config,git-like,config lib,write conf
+Author: Daniel Bosk
+Author-email: daniel@bosk.se
+Requires-Python: >=3.7,<4.0
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Utilities
+Requires-Dist: appdirs (>=1.4.4,<2.0.0)
+Requires-Dist: typer (>=0.7.0,<0.8.0)
+Project-URL: Bug Tracker, https://github.com/dbosk/typerconf/issues
+Project-URL: Repository, https://github.com/dbosk/typerconf
+Project-URL: Releases, https://github.com/dbosk/typerconf/releases
+Description-Content-Type: text/markdown
+
+The configuration is a JSON structure. We'll use the following for the
+coming examples.
+
+```JSON
+{
+  "courses": {
+    "datintro22": {
+      "timesheet": {
+        "url": "https://sheets.google..."
+      },
+      "schedule": {
+        "url": "https://timeedit.net/..."
+      }
+    }
+  }
+}
+```
+
+The format is actually irrelevant to anyone outside of this library,
+since it will never be accessed directly anyway. But it will be used to
+illustrate the examples.
+
+We can access values by dot-separated addresses. For instance, we can
+use `courses.datintro22.schedule.url` to access the TimeEdit URL of the
+datintro22 course.
+
+Let's have a look at some usage examples. Say we have the program
+`nytid` that wants to use this config module and subcommand.
+
+```python
+import typer
+import typerconf as config
+
+cli = typer.Typer()
+# add some other subcommands
+config.add_config_cmd(cli)
+```
+
+We want the CLI command to have the following form when used with
+`nytid`.
+
+```bash
+  nytid config courses.datintro22.schedule.url --set https://timeedit.net/...
+```
+
+will set the configuration value at the path, whereas
+
+```bash
+  nytid config courses.datintro22.schedule.url
+```
+
+will return it.
+
+Internally, `nytid`'s different parts can access the config through the
+following API.
+
+```python
+import typerconf as config
+
+url = config.get("courses.datintro22.schedule.url")
+```
+

typerconf-1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+typerconf/.gitignore,sha256=14GNAIXVZFnTv4YhegCyrOBnN79i2rSEKdcShzPmZZE,30
+typerconf/Makefile,sha256=1l7-qXX_bMGudBSDP3T2S6TtxmFN1tKbf7RNPUEBci8,258
+typerconf/__init__.py,sha256=T83A7OS70bzs1D075zV1JfYSzjeX1a2-spk_hajO5e4,5930
+typerconf/init.nw,sha256=f0MtVu_8wna9mD9S033B5T-7FYW6AsvRcJO2M6RDqMY,11988
+typerconf-1.0.dist-info/LICENSE,sha256=MAeY6b3f2eyrZasde3JOsc6TzcZF7tLdNPPnwVdsqz4,1074
+typerconf-1.0.dist-info/METADATA,sha256=xzL8k8J2f12vey56R1jlNB5V7FJW92rsF7rusVC-Oqw,2508
+typerconf-1.0.dist-info/WHEEL,sha256=kLuE8m1WYU0Ig0_YEGrXyTtiJvKPpLpDEiChiNyei5Y,88
+typerconf-1.0.dist-info/RECORD,,

typerconf-1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 1.5.1
+Root-Is-Purelib: true
+Tag: py3-none-any