pyrecli 0.2.0__tar.gz → 0.3.0__tar.gz

pyrecli-0.3.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: pyrecli
+Version: 0.3.0
+Summary: Command line utilities for DiamondFire templates
+License-Expression: MIT
+License-File: LICENSE
+Keywords: diamondfire,minecraft,template,cli,tools
+Author: Amp
+Requires-Python: >=3.10
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Provides-Extra: dev
+Requires-Dist: dfpyre (>=0.9.5)
+Requires-Dist: pytest (>=9.0.2) ; extra == "dev"
+Requires-Dist: rapidnbt (>=1.3.3)
+Requires-Dist: twine (>=6.2.0) ; extra == "dev"
+Project-URL: Repository, https://github.com/Amp63/pyrecli
+Description-Content-Type: text/markdown
+
+# pyrecli
+
+Command line utilities for DiamondFire templates
+
+## Installation
+
+Run the following command in a terminal:
+
+```sh
+pip install pyrecli
+```
+
+## Commands
+
+- `scan`: Scan all templates on the plot and dump them to a text file (requires [CodeClient](github.com/DFOnline/CodeClient))
+- `send`: Send template items to DiamondFire (requires [CodeClient](github.com/DFOnline/CodeClient))
+- `rename`: Rename all occurences of a variable (including text codes)
+- `script`: Generate python scripts from template data
+- `grabinv`: Save all templates in your Minecraft inventory to a file (requires [CodeClient](github.com/DFOnline/CodeClient))
+- `docs`: Generate markdown documentation from template data
+- `slice`: Slice a template into multiple smaller templates
+- `cctoken`: Get a reusable CodeClient authentication token
+
+
+## What is this useful for?
+
+- Backing up a plot
+- Getting an accurate text representation of DF code
+- Open sourcing
+- Version control
+- Large scale refactoring
+
+
+## Example Command Usages
+
+### Scan
+
+**[Requires CodeClient]**
+
+Grabs all of the templates on your current plot and saves them to a file.
+You will need to run `/auth` in-game to authorize this action.
+
+Example:
+```sh
+# Dumps all template data into templates.dfts
+pyrecli scan templates.dfts
+```
+
+### Send
+
+**[Requires CodeClient]**
+
+Sends all templates in a file back to your inventory.
+
+Example:
+```sh
+pyrecli send templates.dfts
+```
+
+### Rename
+
+Renames all occurences of a variable in a list of templates.
+You can run this command on a single template, or on an entire plot if a variable is used in many places.
+
+This command still requires thorough testing, so make sure you have a backup of your plot before using this command on a large scale.
+
+Example:
+```sh
+# Changes all variables named `foo` to `bar`.
+pyrecli rename templates.dfts foo bar
+
+# You can also target a specific scope.
+# This changes all occurences of the game variable `plotData` to `gameData`.
+pyrecli rename templates.dfts plotData gameData -s game
+```
+
+By default, this modifies the input file in-place, but you can use the `--output_path` flag to output the renamed templates to a new file:
+```sh
+pyrecli rename templates.dfts foo bar --output_path renamed_templates.dfts
+```
+
+### Script
+
+Generates Python scripts from template data.
+
+Example:
+```sh
+# Convert templates into individual scripts and store them in directory `plot_templates`
+pyrecli script templates.dfts plot_templates
+
+# Convert templates into scripts and put them into a single file `plot_templates.py`
+pyrecli script templates.dfts plot_templates.py --onefile
+```
+
+
+### Grabinv
+
+**[Requires CodeClient]**
+
+Scans your inventory for templates and saves them to a file.
+
+Example:
+```sh
+# Save inventory templates to `templates.dfts`
+pyrecli grabinv templates.dfts
+```
+
+
+### Docs
+
+Generates a Markdown documentation file for a list of templates.
+
+Example:
+```sh
+# Generate documentation and save it to `plot_docs.md`
+pyrecli docs templates.dfts plot_docs.md "My Plot Docs"
+```
+
+
+### Slice
+
+Slices a single template into multiple smaller templates.
+This is useful for resizing templates to fit on a smaller plot.
+
+If multiple templates are passed, only the first one will be used.
+
+**NOTE: This feature is not fully implemented yet. Any templates with Control::Return blocks may not work properly if sliced.**
+
+Example:
+```sh
+# Slices the first template in `templates.dfts` with a target length of 50 and stores them in `sliced_templates.dfts`
+pyrecli slice templates.dfts sliced_templates.dfts 50
+```
+
+
+### CCToken
+
+Returns a CodeClient authentication token that can be used in commands that require CodeClient authorization.
+This is useful for reducing the amount of times you need to run `/auth`.
+
+Example:
+```sh
+# Get a token with the read_plot and inventory scopes
+pyrecli cctoken mytoken.txt "read_plot inventory"
+```
+
+
+### Command Chaining
+
+You can combine the pipe operator (`|`) with hyphen (`-`) file paths to chain multiple commands together.
+
+Example:
+```sh
+# Scans the plot, renames a variable, then sends renamed templates back to DiamondFire
+pyrecli scan - | pyrecli rename - foo bar | pyrecli send -
+
+```

pyrecli-0.3.0/README.md

@@ -0,0 +1,157 @@
+# pyrecli
+
+Command line utilities for DiamondFire templates
+
+## Installation
+
+Run the following command in a terminal:
+
+```sh
+pip install pyrecli
+```
+
+## Commands
+
+- `scan`: Scan all templates on the plot and dump them to a text file (requires [CodeClient](github.com/DFOnline/CodeClient))
+- `send`: Send template items to DiamondFire (requires [CodeClient](github.com/DFOnline/CodeClient))
+- `rename`: Rename all occurences of a variable (including text codes)
+- `script`: Generate python scripts from template data
+- `grabinv`: Save all templates in your Minecraft inventory to a file (requires [CodeClient](github.com/DFOnline/CodeClient))
+- `docs`: Generate markdown documentation from template data
+- `slice`: Slice a template into multiple smaller templates
+- `cctoken`: Get a reusable CodeClient authentication token
+
+
+## What is this useful for?
+
+- Backing up a plot
+- Getting an accurate text representation of DF code
+- Open sourcing
+- Version control
+- Large scale refactoring
+
+
+## Example Command Usages
+
+### Scan
+
+**[Requires CodeClient]**
+
+Grabs all of the templates on your current plot and saves them to a file.
+You will need to run `/auth` in-game to authorize this action.
+
+Example:
+```sh
+# Dumps all template data into templates.dfts
+pyrecli scan templates.dfts
+```
+
+### Send
+
+**[Requires CodeClient]**
+
+Sends all templates in a file back to your inventory.
+
+Example:
+```sh
+pyrecli send templates.dfts
+```
+
+### Rename
+
+Renames all occurences of a variable in a list of templates.
+You can run this command on a single template, or on an entire plot if a variable is used in many places.
+
+This command still requires thorough testing, so make sure you have a backup of your plot before using this command on a large scale.
+
+Example:
+```sh
+# Changes all variables named `foo` to `bar`.
+pyrecli rename templates.dfts foo bar
+
+# You can also target a specific scope.
+# This changes all occurences of the game variable `plotData` to `gameData`.
+pyrecli rename templates.dfts plotData gameData -s game
+```
+
+By default, this modifies the input file in-place, but you can use the `--output_path` flag to output the renamed templates to a new file:
+```sh
+pyrecli rename templates.dfts foo bar --output_path renamed_templates.dfts
+```
+
+### Script
+
+Generates Python scripts from template data.
+
+Example:
+```sh
+# Convert templates into individual scripts and store them in directory `plot_templates`
+pyrecli script templates.dfts plot_templates
+
+# Convert templates into scripts and put them into a single file `plot_templates.py`
+pyrecli script templates.dfts plot_templates.py --onefile
+```
+
+
+### Grabinv
+
+**[Requires CodeClient]**
+
+Scans your inventory for templates and saves them to a file.
+
+Example:
+```sh
+# Save inventory templates to `templates.dfts`
+pyrecli grabinv templates.dfts
+```
+
+
+### Docs
+
+Generates a Markdown documentation file for a list of templates.
+
+Example:
+```sh
+# Generate documentation and save it to `plot_docs.md`
+pyrecli docs templates.dfts plot_docs.md "My Plot Docs"
+```
+
+
+### Slice
+
+Slices a single template into multiple smaller templates.
+This is useful for resizing templates to fit on a smaller plot.
+
+If multiple templates are passed, only the first one will be used.
+
+**NOTE: This feature is not fully implemented yet. Any templates with Control::Return blocks may not work properly if sliced.**
+
+Example:
+```sh
+# Slices the first template in `templates.dfts` with a target length of 50 and stores them in `sliced_templates.dfts`
+pyrecli slice templates.dfts sliced_templates.dfts 50
+```
+
+
+### CCToken
+
+Returns a CodeClient authentication token that can be used in commands that require CodeClient authorization.
+This is useful for reducing the amount of times you need to run `/auth`.
+
+Example:
+```sh
+# Get a token with the read_plot and inventory scopes
+pyrecli cctoken mytoken.txt "read_plot inventory"
+```
+
+
+### Command Chaining
+
+You can combine the pipe operator (`|`) with hyphen (`-`) file paths to chain multiple commands together.
+
+Example:
+```sh
+# Scans the plot, renames a variable, then sends renamed templates back to DiamondFire
+pyrecli scan - | pyrecli rename - foo bar | pyrecli send -
+
+```

pyrecli-0.3.0/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "pyrecli"
+version = "0.3.0"
+description = "Command line utilities for DiamondFire templates"
+authors = [
+    {name = "Amp"}
+]
+license = "MIT"
+readme = "README.md"
+keywords = ["diamondfire", "minecraft", "template", "cli", "tools"]
+
+requires-python = ">=3.10"
+dependencies = [
+    "dfpyre>=0.9.5",
+    "rapidnbt>=1.3.3"
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=9.0.2",
+    "twine>=6.2.0"
+]
+
+[project.urls]
+Repository = "https://github.com/Amp63/pyrecli"
+
+
+[tool.poetry.scripts]
+pyrecli = "pyrecli.pyrecli:main"
+
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

pyrecli-0.3.0/pyrecli/command/cctoken.py

@@ -0,0 +1,10 @@
+from pyrecli.util import connect_to_codeclient, write_output_file
+
+
+def cctoken_command(output_path: str, scopes: str):
+    ws = connect_to_codeclient(scopes)
+
+    ws.send('token')
+    token = ws.recv().replace('token ', '')
+
+    write_output_file(output_path, token)

{pyrecli-0.2.0 → pyrecli-0.3.0}/pyrecli/command/docs.py

@@ -1,5 +1,4 @@
 from typing import Literal, TypedDict
-from result import Result, Err
 from dfpyre import DFTemplate, Item, Parameter
 from mcitemlib.itemlib import MCItemlibException
 from pyrecli.util import read_input_file, write_output_file, parse_templates_from_string
@@ -24,15 +23,9 @@ class TemplateDocData(TypedDict):
     doc_lines: list[str]
 
 
-def docs_command(input_path: str, output_path: str, title: str, include_hidden: bool, omit_toc: bool) -> Result[None, str]:
-    input_result = read_input_file(input_path)
-    if input_result.is_err():
-        return Err(input_result.err_value)
-
-    templates_result = parse_templates_from_string(input_result.ok_value)
-    if templates_result.is_err():
-        return Err(templates_result.err_value)
-    templates = templates_result.ok_value
+def docs_command(input_path: str, output_path: str, title: str, include_hidden: bool, omit_toc: bool):
+    templates_string = read_input_file(input_path)
+    templates = parse_templates_from_string(templates_string)
 
     def get_function_name(template: DFTemplate) -> str:
         first_block = template.codeblocks[0]
@@ -72,7 +65,7 @@ def docs_command(input_path: str, output_path: str, title: str, include_hidden:
                     lore_text = [escape_md(l.to_string()) for l in first_arg.get_lore()]
                     if lore_text:
                         template_doc_lines.extend(lore_text)
-                except (MCItemlibException, AttributeError):
+                except:
                     # There are so many things that can go wrong here due to various legacy
                     # item formats and weird MC string edge cases, so we can just skip
                     # if there's a problem.
@@ -120,5 +113,4 @@ def docs_command(input_path: str, output_path: str, title: str, include_hidden:
         output_lines.extend(doc_data['doc_lines'])
         output_lines.append('')
     
-    write_result = write_output_file(output_path, '\n'.join(output_lines))
-    return write_result
+    write_output_file(output_path, '\n'.join(output_lines))

pyrecli-0.3.0/pyrecli/command/grabinv.py

@@ -0,0 +1,44 @@
+import json
+from rapidnbt import nbtio, CompoundTagVariant
+from pyrecli.util import write_output_file, connect_to_codeclient, print_status
+
+
+def grabinv_command(output_path: str, token: str|None=None):
+    ws = connect_to_codeclient('inventory', token)
+
+    ws.send('inv')
+    inventory = ws.recv()
+    ws.close()
+
+    inventory = f'{{inventory:{inventory}}}'
+    inventory_nbt = nbtio.loads_snbt(inventory)
+
+    template_codes: list[str] = []
+    for tag in inventory_nbt['inventory']:
+        tag: CompoundTagVariant
+        components = tag['components']
+        if components.is_null():
+            continue
+
+        custom_data = components['minecraft:custom_data']
+        if custom_data.is_null():
+            continue
+            
+        pbv_tag = custom_data['PublicBukkitValues']
+        if pbv_tag.is_null():
+            continue
+        
+        code_template_data = pbv_tag['hypercube:codetemplatedata']
+        if code_template_data.is_null():
+            continue
+        
+        code_template_json = json.loads(code_template_data.get_string())
+        
+        template_code = code_template_json.get('code')
+        if template_code:
+            template_codes.append(template_code)
+
+    if not template_codes:
+        print_status('Could not find any templates in the inventory.')
+
+    write_output_file(output_path, '\n'.join(template_codes))

{pyrecli-0.2.0 → pyrecli-0.3.0}/pyrecli/command/rename.py

@@ -1,7 +1,6 @@
 from typing import Literal
 import re
-from result import Result, Err
-from dfpyre import Variable, Number, String, Text
+from dfpyre import Variable, Number, String, Text, Parameter
 from pyrecli.util import read_input_file, write_output_file, parse_templates_from_string
 
 
@@ -22,33 +21,34 @@ def rename_var_in_text_code(s: str, var_to_rename: str, new_var_name: str):
 
 def rename_command(input_path: str, output_path: str|None,
                    var_to_rename: str, new_var_name: str,
-                   var_to_rename_scope: Literal['game', 'saved', 'local', 'line']|None) -> Result[None, str]:
+                   var_to_rename_scope: Literal['game', 'saved', 'local', 'line']|None):
     
-    input_result = read_input_file(input_path)
-    if input_result.is_err():
-        return Err(input_result.err_value)
-
-    templates_result = parse_templates_from_string(input_result.ok_value)
-    if templates_result.is_err():
-        return Err(templates_result.err_value)
-    templates = templates_result.ok_value
+    templates_string = read_input_file(input_path)
+    templates = parse_templates_from_string(templates_string)
 
     for template in templates:
         for codeblock in template.codeblocks:
             for argument in codeblock.args:
+                # Try to rename variable
                 if isinstance(argument, Variable):
                     if argument.name == var_to_rename and (var_to_rename_scope is None or argument.scope == var_to_rename_scope):
                         argument.name = new_var_name
                     argument.name = rename_var_in_text_code(argument.name, var_to_rename, new_var_name)
                 
+                # Try to rename parameter
+                elif isinstance(argument, Parameter) and var_to_rename_scope == 'line':
+                    if argument.name == var_to_rename:
+                        argument.name = new_var_name
+                
+                # Check for occurrences of the variable in text codes
                 elif isinstance(argument, (Number, String, Text)) and isinstance(argument.value, str):
                     argument.value = rename_var_in_text_code(argument.value, var_to_rename, new_var_name)
             
+            # Check for text codes in function calls
             if codeblock.type in {'call_func', 'start_process'}:
                 new_data = rename_var_in_text_code(codeblock.data.get('data'), var_to_rename, new_var_name)
                 codeblock.data['data'] = new_data
     
     new_file_content = '\n'.join(t.build() for t in templates)
     write_path = output_path if output_path else input_path
-    write_result = write_output_file(write_path, new_file_content)
-    return write_result 
+    write_output_file(write_path, new_file_content)

pyrecli-0.3.0/pyrecli/command/scan.py

@@ -0,0 +1,14 @@
+from pyrecli.util import write_output_file, connect_to_codeclient, print_status
+
+
+def scan_command(output_path: str, token: str|None=None):
+    ws = connect_to_codeclient('read_plot', token)
+
+    print_status('Scanning plot...')
+    ws.send('scan')
+
+    scan_results = ws.recv()
+    print_status('Done.')
+    ws.close()
+
+    write_output_file(output_path, scan_results)

{pyrecli-0.2.0 → pyrecli-0.3.0}/pyrecli/command/script.py

@@ -1,26 +1,20 @@
 import os
-from result import Result, Ok, Err
 from dfpyre import DFTemplate
 from pyrecli.util import read_input_file, write_output_file, parse_templates_from_string
 
 
-def write_to_directory(dir_name: str, templates: list[DFTemplate], flags: dict[str, int|bool]) -> Result[None, str]:
+def write_to_directory(dir_name: str, templates: list[DFTemplate], flags: dict[str, int|bool]):
     if not os.path.isdir(dir_name):
         os.mkdir(dir_name)
     
     for template in templates:
         script_path = f'{dir_name}/{template._get_template_name()}.py'
         script_string = template.generate_script(**flags)
-        try:
-            with open(script_path, 'w') as f:
-                f.write(script_string)
-        except OSError as e:
-            return Err(str(e))
-    
-    return Ok(None)
+        with open(script_path, 'w') as f:
+            f.write(script_string)
 
 
-def write_to_single_file(file_path: str, templates: list[DFTemplate], flags: dict[str, int|bool]) -> Result[None, str]:
+def write_to_single_file(file_path: str, templates: list[DFTemplate], flags: dict[str, int|bool]):
     file_content = []
     for i, template in enumerate(templates):
         if i == 0:
@@ -29,18 +23,12 @@ def write_to_single_file(file_path: str, templates: list[DFTemplate], flags: dic
             template_script = template.generate_script(include_import=False, assign_variable=True, **flags)
         file_content.append(template_script)
     
-    return write_output_file(file_path, '\n\n'.join(file_content))
-
+    write_output_file(file_path, '\n\n'.join(file_content))
 
-def script_command(input_path: str, output_path: str, one_file: bool, flags: dict[str, int|bool]) -> Result[None, str]:
-    input_result = read_input_file(input_path)
-    if input_result.is_err():
-        return Err(input_result.err_value)
 
-    templates_result = parse_templates_from_string(input_result.ok_value)
-    if templates_result.is_err():
-        return Err(templates_result.err_value)
-    templates = templates_result.ok_value
+def script_command(input_path: str, output_path: str, one_file: bool, flags: dict[str, int|bool]):
+    templates_string = read_input_file(input_path)
+    templates = parse_templates_from_string(templates_string)
     
     if one_file or output_path == '-':
         return write_to_single_file(output_path, templates, flags)

pyrecli-0.3.0/pyrecli/command/send.py

@@ -0,0 +1,16 @@
+from pyrecli.util import connect_to_codeclient, read_input_file, parse_templates_from_string, print_status
+
+
+def send_command(input_path: str):
+    templates_string = read_input_file(input_path)
+    templates = parse_templates_from_string(templates_string)
+
+    ws = connect_to_codeclient()
+
+    for template in templates:
+        item = template.generate_template_item()
+        ws.send(f'give {item.get_snbt()}')
+    
+    ws.close()
+    
+    print_status(f'Sent {len(templates)} template{"s" if len(templates) != 1 else ''} successfully.')

pyrecli-0.3.0/pyrecli/command/slice.py

@@ -0,0 +1,15 @@
+from pyrecli.util import read_input_file, write_output_file, parse_templates_from_string, NoTemplatesError
+
+
+def slice_command(input_path: str, output_path: str, target_length: int):
+    templates_string = read_input_file(input_path)
+    templates = parse_templates_from_string(templates_string)
+
+    if not templates:
+        raise NoTemplatesError(f'Could not find any templates in {input_path}')
+    
+    first_template = templates[0]
+    sliced_templates = first_template.slice(target_length)
+    built_templates = [t.build() for t in sliced_templates]
+
+    write_output_file(output_path, '\n'.join(built_templates))

{pyrecli-0.2.0 → pyrecli-0.3.0}/pyrecli/pyrecli.py

@@ -9,6 +9,15 @@ from pyrecli.command.rename import rename_command
 from pyrecli.command.grabinv import grabinv_command
 from pyrecli.command.docs import docs_command
 from pyrecli.command.slice import slice_command
+from pyrecli.command.cctoken import cctoken_command
+from pyrecli.util import print_status
+
+
+def rename_target_scope(value):
+    SCOPES = {'game', 'saved', 'local', 'line'}
+    if value not in SCOPES:
+        raise argparse.ArgumentTypeError(f'Expected one of {SCOPES} for rename target scope')
+    return value
 
 
 def slice_target_length(value):
@@ -19,13 +28,14 @@ def slice_target_length(value):
     return ivalue
 
 
-def main():
+def main() -> int:
     parser = argparse.ArgumentParser(prog='pyrecli', description='Command line utilities for DiamondFire templates')
     parser.add_argument('--version', '-v', action='version', version=f'pyrecli {importlib.metadata.version('pyrecli')}')
     subparsers = parser.add_subparsers(dest='command', help='Available commands:', required=True, metavar='<command>')
 
     parser_scan = subparsers.add_parser('scan', help='Scan the current plot templates with CodeClient')
     parser_scan.add_argument('output_path', help='The file to output template data to', type=str)
+    parser_scan.add_argument('--token', '-t', help='The CodeClient authentication token to use', type=str, default=None)
 
     parser_send = subparsers.add_parser('send', help='Send templates to DiamondFire with CodeClient')
     parser_send.add_argument('input_path', help='The file containing template data', type=str)
@@ -40,20 +50,21 @@ def main():
     parser_script.add_argument('--preserve_slots', '-s', help='Save the positions of items within chests', action='store_true')
     parser_script.add_argument('--build_and_send', '-b', help='Add `.build_and_send()` to the end of the generated template(s)', action='store_true')
 
-    parser_rename = subparsers.add_parser('rename', help='Rename a variable')
+    parser_rename = subparsers.add_parser('rename', help='Rename all occurrences of a variable')
     parser_rename.add_argument('input_path', help='The file containing template data', type=str)
     parser_rename.add_argument('var_to_rename', help='The variable to rename', type=str)
     parser_rename.add_argument('new_var_name', help='The new name for the variable', type=str)
-    parser_rename.add_argument('--var_to_rename_scope', '-s', help='The scope to match', type=str, default=None)
+    parser_rename.add_argument('--var_scope', '-s', help='The scope to match', type=rename_target_scope, default=None)
     parser_rename.add_argument('--output_path', '-o', help='The file to output to', type=str, default=None)
 
     parser_grabinv = subparsers.add_parser('grabinv', help='Save all templates in the inventory to a file with CodeClient')
     parser_grabinv.add_argument('output_path', help='The file to output template data to', type=str)
+    parser_grabinv.add_argument('--token', '-t', help='The CodeClient authentication token to use', type=str, default=None)
 
     parser_docs = subparsers.add_parser('docs', help='Generate markdown documentation from template data')
     parser_docs.add_argument('input_path', help='The file containing template data', type=str)
     parser_docs.add_argument('output_path', help='The file to output to', type=str)
-    parser_docs.add_argument('title', help='The title for the docs', type=str)
+    parser_docs.add_argument('--title', '-t', help='The title for the docs', type=str, default='Template Docs')
     parser_docs.add_argument('--include_hidden', '-ih', help='Include hidden functions and processes', action='store_true')
     parser_docs.add_argument('--notoc', help='Omit the table of contents', action='store_true')
 
@@ -61,52 +72,61 @@ def main():
     parser_slice.add_argument('input_path', help='The file containing template data', type=str)
     parser_slice.add_argument('output_path', help='The file to output template data to', type=str)
     parser_slice.add_argument('target_length', help='The maximum length of each sliced template', type=slice_target_length)
-    
+
+    parser_cctoken = subparsers.add_parser('cctoken', help='Request a CodeClient token with the specified scopes')
+    parser_cctoken.add_argument('output_path', help='The file to output the token to', type=str)
+    parser_cctoken.add_argument('scopes', help='The scopes to request', type=str)
+
+
     parsed_args = parser.parse_args()
 
-    match parsed_args.command:
-        case 'scan':
-            command_result = scan_command(parsed_args.output_path)
-        
-        case 'send':
-            command_result = send_command(parsed_args.input_path)
-        
-        case 'script':
-            scriptgen_flags = {
-                'indent_size': parsed_args.indent_size, 
-                'literal_shorthand': parsed_args.literal_shorthand,
-                'var_shorthand': parsed_args.var_shorthand,
-                'preserve_slots': parsed_args.preserve_slots,
-                'build_and_send': parsed_args.build_and_send
-            }
-            command_result = script_command(parsed_args.input_path, parsed_args.output_path, parsed_args.onefile, scriptgen_flags)
-        
-        case 'rename':
-            command_result = rename_command(
-                parsed_args.input_path, parsed_args.output_path,
-                parsed_args.var_to_rename, parsed_args.new_var_name, parsed_args.var_to_rename_scope
-            )
-        
-        case 'grabinv':
-            command_result = grabinv_command(parsed_args.output_path)
-        
-        case 'docs':
-            command_result = docs_command(
-                parsed_args.input_path, parsed_args.output_path,
-                parsed_args.title, parsed_args.include_hidden, parsed_args.notoc
-            )
-        
-        case 'slice':
-            command_result = slice_command(
-                parsed_args.input_path, parsed_args.output_path,
-                parsed_args.target_length
-            )
+    try:
+        match parsed_args.command:
+            case 'scan':
+                scan_command(parsed_args.output_path, parsed_args.token)
+            
+            case 'send':
+                send_command(parsed_args.input_path)
+            
+            case 'script':
+                scriptgen_flags = {
+                    'indent_size': parsed_args.indent_size, 
+                    'literal_shorthand': parsed_args.literal_shorthand,
+                    'var_shorthand': parsed_args.var_shorthand,
+                    'preserve_slots': parsed_args.preserve_slots,
+                    'build_and_send': parsed_args.build_and_send
+                }
+                script_command(parsed_args.input_path, parsed_args.output_path, parsed_args.onefile, scriptgen_flags)
+            
+            case 'rename':
+                rename_command(
+                    parsed_args.input_path, parsed_args.output_path,
+                    parsed_args.var_to_rename, parsed_args.new_var_name, parsed_args.var_scope
+                )
+            
+            case 'grabinv':
+                grabinv_command(parsed_args.output_path, parsed_args.token)
+            
+            case 'docs':
+                docs_command(
+                    parsed_args.input_path, parsed_args.output_path,
+                    parsed_args.title, parsed_args.include_hidden, parsed_args.notoc
+                )
+            
+            case 'slice':
+                slice_command(
+                    parsed_args.input_path, parsed_args.output_path,
+                    parsed_args.target_length
+                )
+            
+            case 'cctoken':
+                cctoken_command(parsed_args.output_path, parsed_args.scopes)
     
-    if command_result.is_err():
-        print(command_result.err_value)
-        sys.exit(1)
+    except Exception as e:
+        print_status(e)
+        return 1
     
-    sys.exit(0)
+    return 0
 
 if __name__ == '__main__':
-    main()
+    sys.exit(main())

pyrecli-0.3.0/pyrecli/util.py

@@ -0,0 +1,132 @@
+import os
+import re
+import sys
+import websocket
+from dfpyre import DFTemplate
+
+
+CODECLIENT_URL = 'ws://localhost:31375'
+
+BASE64_REGEX = re.compile(r'^[A-Za-z0-9+/]+={0,2}$')
+
+class TemplateParsingError(Exception):
+    """Exception class for DFTemplate parsing errors"""
+
+class NoTemplatesError(Exception):
+    """Exception class for empty template list"""
+
+
+def print_status(*args, **kwargs):
+    """Prints a message to stderr"""
+    print(*args, **kwargs, file=sys.stderr)
+
+
+def connect_to_codeclient(scopes: str|None=None, token: str|None=None) -> websocket.WebSocket:
+    """
+    Tries to connect to the CodeClient websocket server with the specified scopes.
+
+    Args:
+        scopes: The scopes to request
+        token: The CodeClient authentication token to use
+
+    Returns:
+        The connected websocket
+
+    Raises:
+        ConnectionRefusedError: If connection to the server could not be established
+        PermissionError: If scope authentication fails
+    """
+    ws = websocket.WebSocket()
+    ws.connect(CODECLIENT_URL)
+    
+    print_status('Connected to CodeClient.')
+
+    if token:
+        ws.send(f'token {token}')
+        auth_message = ws.recv()
+    elif scopes:
+        print_status('Please run /auth in game.')
+        ws.send(f'scopes {scopes}')
+        auth_message = ws.recv()
+    
+    if (token or scopes):
+        if auth_message != 'auth':
+            raise PermissionError('Failed to authenticate.')
+        else:
+            print_status('Authentication successful.')
+    
+    return ws
+
+
+def parse_templates_from_string(templates: str) -> list[DFTemplate]:
+    """
+    Parses a newline-delimited string of template codes into a list of templates.
+    
+    Args:
+        templates: The string of templates to parse
+    
+    Returns:
+        The list of parsed templates
+    
+    Raises:
+        ValueError: If a template code is not a valid base64 string
+        TemplateParsingError: If a template failed to parse
+    """
+    template_codes = templates.split('\n')
+    
+    for i, template_code in enumerate(template_codes):
+        if not BASE64_REGEX.match(template_code):
+            raise ValueError(f'Template code at line {i+1} is not a base64 string.')
+    
+    try:
+        return [DFTemplate.from_code(c) for c in template_codes]
+    except Exception as e:
+        raise TemplateParsingError(f'Error while parsing template: {e}') from None
+
+
+def read_input_file(path: str) -> str:
+    """
+    Returns the string content of the file at a specified path.
+    If the path is a hyphen ('-'), then input will be read from stdin.
+
+    Args:
+        path: The file path to read
+    
+    Returns:
+        The file content or input from stdin
+    
+    Raises:
+        FileNotFoundError: If the path is not a file or the file doesn't exist
+        OSError: If the file was unable to be opened or read
+    """
+    if path == '-':
+        try:
+            input_string = sys.stdin.read()
+        except EOFError:
+            pass
+        return input_string.strip()
+    
+    if not os.path.isfile(path):
+        raise FileNotFoundError(f'"{path}" is not a file.')
+    
+    with open(path, 'r') as f:
+        return f.read()
+
+
+def write_output_file(path: str, content: str):
+    """
+    Writes string content to a specified file.
+    If the file path is a hyphen ('-') then the content will be printed to stdout.
+
+    Args:
+        path: The file path to write to
+        content: The string content to write
+    
+    Raises:
+        OSError: If the file was unable to be accessed
+    """
+    if path == '-':
+        print(content, end='')
+    else:
+        with open(path, 'w') as f:
+            f.write(content)

pyrecli-0.2.0/PKG-INFO

@@ -1,66 +0,0 @@
-Metadata-Version: 2.1
-Name: pyrecli
-Version: 0.2.0
-Summary: Command line utilities for DiamondFire templates
-Home-page: https://github.com/Amp63/pyrecli
-License: MIT
-Keywords: diamondfire,minecraft,template,cli
-Author: Amp
-Requires-Python: >=3.10,<3.13
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Project-URL: Repository, https://github.com/Amp63/pyrecli
-Description-Content-Type: text/markdown
-
-# pyrecli
-
-Command line utilities for DiamondFire templates
-
-## Installation
-
-Run the following command in a terminal:
-
-```sh
-pip install pyrecli
-```
-
-## Commands
-
-- `scan`: Scan all templates on the plot and dump them to a text file (requires [CodeClient](github.com/DFOnline/CodeClient))
-- `send`: Send template items to DiamondFire (requires [CodeClient](github.com/DFOnline/CodeClient))
-- `rename`: Rename all occurences of a variable (including text codes)
-- `script`: Generate python scripts from template data
-- `grabinv`: Save all templates in your Minecraft inventory to a file (requires [CodeClient](github.com/DFOnline/CodeClient))
-- `docs`: Generate markdown documentation from template data
-
-
-## What is this useful for?
-
-- Backing up a plot
-- Getting an accurate text representation of DF code
-- Open sourcing
-- Version control
-- Large scale refactoring
-
-
-## Example Usage
-
-These two commands will scan your plot, convert each template into a python script, then place the scripts into a directory called `myplot`.
-
-```sh
-pyrecli scan templates.dfts
-pyrecli script templates.dfts myplot
-```
-
-If you prefer the templates to be outputted to a single file, use the `--onefile` flag:
-
-```sh
-pyrecli scan templates.dfts
-pyrecli script templates.dfts myplot.py --onefile
-```
-
-For more information about generating scripts, run `pyrecli script -h`.
-

pyrecli-0.2.0/README.md

@@ -1,48 +0,0 @@
-# pyrecli
-
-Command line utilities for DiamondFire templates
-
-## Installation
-
-Run the following command in a terminal:
-
-```sh
-pip install pyrecli
-```
-
-## Commands
-
-- `scan`: Scan all templates on the plot and dump them to a text file (requires [CodeClient](github.com/DFOnline/CodeClient))
-- `send`: Send template items to DiamondFire (requires [CodeClient](github.com/DFOnline/CodeClient))
-- `rename`: Rename all occurences of a variable (including text codes)
-- `script`: Generate python scripts from template data
-- `grabinv`: Save all templates in your Minecraft inventory to a file (requires [CodeClient](github.com/DFOnline/CodeClient))
-- `docs`: Generate markdown documentation from template data
-
-
-## What is this useful for?
-
-- Backing up a plot
-- Getting an accurate text representation of DF code
-- Open sourcing
-- Version control
-- Large scale refactoring
-
-
-## Example Usage
-
-These two commands will scan your plot, convert each template into a python script, then place the scripts into a directory called `myplot`.
-
-```sh
-pyrecli scan templates.dfts
-pyrecli script templates.dfts myplot
-```
-
-If you prefer the templates to be outputted to a single file, use the `--onefile` flag:
-
-```sh
-pyrecli scan templates.dfts
-pyrecli script templates.dfts myplot.py --onefile
-```
-
-For more information about generating scripts, run `pyrecli script -h`.

pyrecli-0.2.0/pyproject.toml

@@ -1,22 +0,0 @@
-[tool.poetry]
-name = "pyrecli"
-version = "0.2.0"
-description = "Command line utilities for DiamondFire templates"
-authors = ["Amp"]
-readme = "README.md"
-license = "MIT"
-repository = "https://github.com/Amp63/pyrecli"
-keywords = ["diamondfire", "minecraft", "template", "cli"]
-
-
-[tool.poetry.dependencies]
-python = ">=3.10,<3.13"
-
-
-[tool.poetry.scripts]
-pyrecli = "pyrecli.pyrecli:main"
-
-
-[build-system]
-requires = ["poetry-core"]
-build-backend = "poetry.core.masonry.api"

pyrecli-0.2.0/pyrecli/command/grabinv.py

@@ -1,49 +0,0 @@
-import json
-from result import Result, Ok, Err
-import amulet_nbt
-from amulet_nbt import CompoundTag, StringTag
-from pyrecli.util import write_output_file, connect_to_codeclient
-
-
-def grabinv_command(output_path: str) -> Result[None, str]:
-    ws_result = connect_to_codeclient('inventory')
-    if ws_result.is_err():
-        return Err(ws_result.err_value)
-    ws = ws_result.ok_value
-
-    ws.send('inv')
-    inventory = ws.recv()
-    inventory_nbt = amulet_nbt.from_snbt(inventory)
-
-    template_codes: list[str] = []
-    for tag in inventory_nbt:
-        components: CompoundTag = tag.get('components')
-        if components is None:
-            continue
-
-        custom_data: CompoundTag = components.get('minecraft:custom_data')
-        if custom_data is None:
-            continue
-            
-        pbv_tag: CompoundTag = custom_data.get('PublicBukkitValues')
-        if pbv_tag is None:
-            continue
-        
-        code_template_data: StringTag = pbv_tag.get('hypercube:codetemplatedata')
-        if code_template_data is None:
-            continue
-        
-        code_template_json = json.loads(str(code_template_data))
-        
-        template_code = code_template_json.get('code')
-        if template_code:
-            template_codes.append(template_code)
-
-    if not template_codes:
-        return Err('Could not find any templates in the inventory.')
-
-    output_result = write_output_file(output_path, '\n'.join(template_codes))
-    if output_result.is_err():
-        return output_result
-    
-    return Ok(None)

pyrecli-0.2.0/pyrecli/command/scan.py

@@ -1,19 +0,0 @@
-from result import Result, Err
-from pyrecli.util import write_output_file, connect_to_codeclient
-
-
-def scan_command(output_path: str) -> Result[None, str]:
-    ws_result = connect_to_codeclient('read_plot')
-    if ws_result.is_err():
-        return Err(ws_result.err_value)
-    ws = ws_result.ok_value
-
-    print('Scanning plot...')
-    ws.send('scan')
-
-    scan_results = ws.recv()
-    print('Done.')
-    ws.close()
-
-    write_result = write_output_file(output_path, scan_results)
-    return write_result

pyrecli-0.2.0/pyrecli/command/send.py

@@ -1,26 +0,0 @@
-from result import Result, Ok, Err
-from pyrecli.util import connect_to_codeclient, read_input_file, parse_templates_from_string
-
-
-def send_command(input_path: str) -> Result[None, str]:
-    input_result = read_input_file(input_path)
-    if input_result.is_err():
-        return Err(input_result.err_value)
-
-    templates_result = parse_templates_from_string(input_result.ok_value)
-    if templates_result.is_err():
-        return Err(templates_result.err_value)
-    templates = templates_result.ok_value
-
-    ws_result = connect_to_codeclient()
-    if ws_result.is_err():
-        return Err(ws_result.err_value)
-    ws = ws_result.ok_value
-
-    for template in templates:
-        item = template.generate_template_item()
-        ws.send(f'give {item.get_snbt()}')
-    
-    ws.close()
-    print(f'Sent {len(templates)} template{"s" if len(templates) != 1 else ''} successfully.')
-    return Ok(None)

pyrecli-0.2.0/pyrecli/command/slice.py

@@ -1,21 +0,0 @@
-from result import Result, Err
-from pyrecli.util import read_input_file, write_output_file, parse_templates_from_string
-
-def slice_command(input_path: str, output_path: str, target_length: int) -> Result[None, str]:
-    input_result = read_input_file(input_path)
-    if input_result.is_err():
-        return Err(input_result.err_value)
-
-    templates_result = parse_templates_from_string(input_result.ok_value)
-    if templates_result.is_err():
-        return Err(templates_result.err_value)
-    templates = templates_result.ok_value
-
-    if not templates:
-        return Err(f'Could not find any templates in {input_path}')
-    
-    first_template = templates[0]
-    sliced_templates = first_template.slice(target_length)
-    built_templates = [t.build() for t in sliced_templates]
-
-    return write_output_file(output_path, '\n'.join(built_templates))

pyrecli-0.2.0/pyrecli/util.py

@@ -1,76 +0,0 @@
-import os
-import re
-import sys
-from result import Result, Ok, Err
-import websocket
-from dfpyre import DFTemplate
-
-
-CODECLIENT_URL = 'ws://localhost:31375'
-
-BASE64_REGEX = re.compile(r'^[A-Za-z0-9+/]+={0,2}$')
-
-
-def connect_to_codeclient(scopes: str|None=None) -> Result[websocket.WebSocket, str]:
-    ws = websocket.WebSocket()
-    try:
-        ws.connect(CODECLIENT_URL)
-    except ConnectionRefusedError:
-        return Err('Failed to connect to CodeClient.')
-    
-    print('Connected to CodeClient.')
-
-    if scopes:
-        print('Please run /auth in game.')
-        ws.send(f'scopes {scopes}')
-        auth_message = ws.recv()
-
-        if auth_message != 'auth':
-            return Err('Failed to authenticate.')
-        print('Authentication received.')
-    
-    return Ok(ws)
-
-
-def parse_templates_from_string(templates: str) -> Result[list[DFTemplate], str]:
-    template_codes = templates.split('\n')
-    
-    for i, template_code in enumerate(template_codes):
-        if not BASE64_REGEX.match(template_code):
-            return Err(f'Template code at line {i+1} is not a base64 string.')
-    
-    try:
-        return Ok([DFTemplate.from_code(c) for c in template_codes])
-    except Exception as e:
-        return Err(str(e))
-
-
-def read_input_file(path: str) -> Result[str, str]:
-    if path == '-':
-        try:
-            input_string = sys.stdin.read()
-        except EOFError:
-            pass
-        return Ok(input_string.strip())
-    
-    if not os.path.isfile(path):
-        return Err(f'"{path}" is not a file.')
-    
-    try:
-        with open(path, 'r') as f:
-            return Ok(f.read())
-    except OSError as e:
-        return Err(str(e))
-
-
-def write_output_file(path: str, content: str) -> Result[None, str]:
-    if path == '-':
-        print(content, end='')
-    else:
-        try:
-            with open(path, 'w') as f:
-                f.write(content)
-        except OSError as e:
-            return Err(str(e))
-
-    return Ok(None)