cs-sh 20260912.1__tar.gz

cs_sh-20260912.1/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: cs-sh
+Version: 20260912.1
+Summary: Convenience functions for constructing shell commands.
+Keywords: python2,python3
+Author-email: Cameron Simpson <cs@cskk.id.au>
+Description-Content-Type: text/markdown
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 2
+Classifier: Programming Language :: Python :: 3
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Project-URL: MonoRepo Commits, https://bitbucket.org/cameron_simpson/css/commits/branch/main
+Project-URL: Monorepo Git Mirror, https://github.com/cameron-simpson/css
+Project-URL: Monorepo Hg/Mercurial Mirror, https://hg.sr.ht/~cameron-simpson/css
+Project-URL: Source, https://github.com/cameron-simpson/css/blob/main/lib/python/cs/sh.py
+
+Convenience functions for constructing shell commands.
+
+*Latest release 20260912.1*:
+Fix project specification.
+
+Functions for safely constructing shell command lines from bare strings.
+Somewhat like the inverse of the shlex stdlib module.
+
+As of Python 3.3 the function `shlex.quote()` does what `quotestr()` does.
+
+As of Python 3.8 the function `shlex.join()` does what `quoteargv()` does.
+
+
+
+Short summary:
+
+
+* `main_shqstr`: shqstr: emit shell-quoted form of the command line arguments.
+
+
+* `quote`: Quote the supplied strings, return a list of the quoted strings.
+
+
+* `quoteargv`: Quote strings, assemble into command string.
+
+
+* `quotestr`: Quote a string for use on a shell command line.
+
+# Functions
+
+## main_shqstr(argv=None)
+
+shqstr: emit shell-quoted form of the command line arguments.
+
+## quote(args)
+
+Quote the supplied strings, return a list of the quoted strings.
+
+As of Python 3.8 the function `shlex.join()` probably does
+what you would have done with the result of this function
+i.e. join the resulting strings together.
+
+## quoteargv(argv)
+
+Quote strings, assemble into command string.
+
+## quotestr(s)
+
+Quote a string for use on a shell command line.
+
+As of Python 3.3 the function `shlex.quote()` is available for this.
+
+# Release Log
+
+
+
+*Release 20260912.1*:
+Fix project specification.
+
+*Release 20260912*:
+Rename quotecmd to quoteargv.
+
+*Release 20210316*:
+Minor doc update.
+
+*Release 20180613*:
+Rework quotestr significantly to provide somewhat friendlier quoting, include "," in the SAFECHARS.
+
+*Release 20170903.2*:
+bugfix __main__ boilerplate after setuptools workaround
+
+*Release 20170903.1*:
+workaround setuptool's slightly dumb console_scripts call of a "main" function
+
+*Release 20170903*:
+shqstr command; new quotecmd(argv) function
+
+*Release 20150118*:
+Extend SAFECHARS to include colon.
+
+*Release 20150111*:
+minor cleanup
+
+*Release 20150107*:
+initial standalone public release

cs_sh-20260912.1/pyproject.toml

@@ -0,0 +1,132 @@
+[project]
+name = "cs-sh"
+description = "Convenience functions for constructing shell commands."
+authors = [
+    { name = "Cameron Simpson", email = "cs@cskk.id.au" },
+]
+keywords = [
+    "python2",
+    "python3",
+]
+dependencies = []
+classifiers = [
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 2",
+    "Programming Language :: Python :: 3",
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)",
+]
+version = "20260912.1"
+
+[project.license]
+text = "GNU General Public License v3 or later (GPLv3+)"
+
+[project.urls]
+"Monorepo Hg/Mercurial Mirror" = "https://hg.sr.ht/~cameron-simpson/css"
+"Monorepo Git Mirror" = "https://github.com/cameron-simpson/css"
+"MonoRepo Commits" = "https://bitbucket.org/cameron_simpson/css/commits/branch/main"
+Source = "https://github.com/cameron-simpson/css/blob/main/lib/python/cs/sh.py"
+
+[project.scripts]
+shqstr = "cs.sh:main_shqstr"
+
+[project.readme]
+text = """
+Convenience functions for constructing shell commands.
+
+*Latest release 20260912.1*:
+Fix project specification.
+
+Functions for safely constructing shell command lines from bare strings.
+Somewhat like the inverse of the shlex stdlib module.
+
+As of Python 3.3 the function `shlex.quote()` does what `quotestr()` does.
+
+As of Python 3.8 the function `shlex.join()` does what `quoteargv()` does.
+
+
+
+Short summary:
+
+
+* `main_shqstr`: shqstr: emit shell-quoted form of the command line arguments.
+
+
+* `quote`: Quote the supplied strings, return a list of the quoted strings.
+
+
+* `quoteargv`: Quote strings, assemble into command string.
+
+
+* `quotestr`: Quote a string for use on a shell command line.
+
+# Functions
+
+## main_shqstr(argv=None)
+
+shqstr: emit shell-quoted form of the command line arguments.
+
+## quote(args)
+
+Quote the supplied strings, return a list of the quoted strings.
+
+As of Python 3.8 the function `shlex.join()` probably does
+what you would have done with the result of this function
+i.e. join the resulting strings together.
+
+## quoteargv(argv)
+
+Quote strings, assemble into command string.
+
+## quotestr(s)
+
+Quote a string for use on a shell command line.
+
+As of Python 3.3 the function `shlex.quote()` is available for this.
+
+# Release Log
+
+
+
+*Release 20260912.1*:
+Fix project specification.
+
+*Release 20260912*:
+Rename quotecmd to quoteargv.
+
+*Release 20210316*:
+Minor doc update.
+
+*Release 20180613*:
+Rework quotestr significantly to provide somewhat friendlier quoting, include \",\" in the SAFECHARS.
+
+*Release 20170903.2*:
+bugfix __main__ boilerplate after setuptools workaround
+
+*Release 20170903.1*:
+workaround setuptool's slightly dumb console_scripts call of a \"main\" function
+
+*Release 20170903*:
+shqstr command; new quotecmd(argv) function
+
+*Release 20150118*:
+Extend SAFECHARS to include colon.
+
+*Release 20150111*:
+minor cleanup
+
+*Release 20150107*:
+initial standalone public release"""
+content-type = "text/markdown"
+
+[build-system]
+build-backend = "flit_core.buildapi"
+requires = [
+    "flit_core >=3.2,<4",
+]
+
+[tool.flit.module]
+name = "cs.sh"

cs_sh-20260912.1/src/cs/sh.py

@@ -0,0 +1,135 @@
+#!/usr/bin/python
+#
+
+r'''
+Convenience functions for constructing shell commands.
+
+Functions for safely constructing shell command lines from bare strings.
+Somewhat like the inverse of the shlex stdlib module.
+
+As of Python 3.3 the function `shlex.quote()` does what `quotestr()` does.
+
+As of Python 3.8 the function `shlex.join()` does what `quoteargv()` does.
+'''
+
+import string
+import sys
+
+__version__ = '20260912.1'
+
+DISTINFO = {
+    'description':
+    "Convenience functions for constructing shell commands.",
+    'keywords': ["python2", "python3"],
+    'classifiers': [
+        "Programming Language :: Python",
+        "Programming Language :: Python :: 2",
+        "Programming Language :: Python :: 3",
+    ],
+    'install_requires': [],
+    'entry_points': {
+        'console_scripts': {
+            'shqstr': 'cs.sh:main_shqstr'
+        },
+    },
+}
+
+# characters than do not need to be quoted
+SAFECHARS = string.digits + string.ascii_letters + '-+_.,/:'
+
+def quote(args):
+  ''' Quote the supplied strings, return a list of the quoted strings.
+
+      As of Python 3.8 the function `shlex.join()` probably does
+      what you would have done with the result of this function
+      i.e. join the resulting strings together.
+  '''
+  return [quotestr(s) for s in args]
+
+def quotestr(s):
+  ''' Quote a string for use on a shell command line.
+
+      As of Python 3.3 the function `shlex.quote()` is available for this.
+  '''
+  # decide how to quote the string:
+  # - empty string: return ''
+  # - all safe: do not quote
+  # - no single quotes: just single quote the string
+  # - funky quoting
+  if not s:
+    return "''"
+  q_count = 0
+  unsafe_count = 0
+  switch_count = 0
+  safe = True
+  for c in s:
+    if c == "'":
+      q_count += 1
+      new_safe = False
+    elif c not in SAFECHARS:
+      unsafe_count += 1
+      new_safe = False
+    else:
+      new_safe = True
+    if safe ^ new_safe:
+      switch_count += 1
+      safe = new_safe
+  if q_count == 0 and unsafe_count == 0:
+    # all safe
+    return s
+  if q_count == 0:
+    # unsafe but no single quotes
+    return "'" + s + "'"
+
+  def flush():
+    ''' Output the pending characters, which are either all safe or all unsafe.
+    '''
+    if offset > start:
+      part = s[start:offset]
+      if not safe:
+        if len(part) == 1:
+          qparts.append("\\")
+        else:
+          qparts.append("'")
+      qparts.append(part)
+      if not safe:
+        if len(part) > 1:
+          qparts.append("'")
+
+  qparts = []
+  start = 0
+  safe = True  # not in quotes
+  for offset, c in enumerate(s):
+    if c == "'" or (safe and c == '\\'):
+      flush()
+      qparts.append('\\')
+      qparts.append(c)
+      start = offset + 1  # do not include this character in the flushable set
+      new_safe = False
+    else:
+      new_safe = c in SAFECHARS
+      if safe ^ new_safe:
+        # mode change
+        flush()
+        start = offset
+        safe = new_safe
+  # advance past final position
+  offset += 1
+  flush()
+  return ''.join(qparts)
+
+def quoteargv(argv):
+  ''' Quote strings, assemble into command string.
+  '''
+  return ' '.join(quote(argv))
+
+def main_shqstr(argv=None):
+  ''' shqstr: emit shell-quoted form of the command line arguments.
+  '''
+  if argv is None:
+    argv = sys.argv
+  argv.pop(0)
+  print(quoteargv(argv))
+
+if __name__ == '__main__':
+  sys.exit(main_shqstr())