yamljson 1.0.0

A simple JSON ↔ YAML converter CLI tool

yamljson

A lightweight command-line tool to convert files between JSON and YAML formats.

Table of Contents

• Overview
• Features
• Requirements
• Installation
• Usage
• Programmatic API
• Project Tree
• How It Works
• Error Cases and Notes
• Development

Overview

yamljson is built for fast, simple, local file conversion:

• Convert .json files to .yaml
• Convert .yaml files to .json
• Use a single command with a predictable output filename

This project is ideal for quick data format switching in scripts, dev tooling, and config workflows.

Features

• Simple CLI command: convert
• Bidirectional conversion: JSON to YAML, YAML to JSON
• UTF-8 file handling
• Human-readable JSON output (indent=4)
• Safe YAML operations (yaml.safe_load, yaml.safe_dump)

Requirements

• Python >=3.8
• PyYAML

Installation

1. Clone the repository

git clone <your-repository-url>
cd yamljson

2. Install locally

pip install .

This registers the CLI script:

convert

Usage

CLI syntax

convert <filename> --to yaml
convert <filename> --to json

Examples

JSON to YAML

convert data.json --to yaml

Output file:

data.yaml

YAML to JSON

convert config.yaml --to json

Output file:

config.json

Common CLI responses

• File not found: <filename> if the input file does not exist
• Invalid option. Use: --to yaml | json if --to is missing
• Unknown target format. Use 'yaml' or 'json'. for unsupported targets
• Conversion failed: <reason> for parsing and file I/O errors

Programmatic API

You can also use the converter functions directly in Python:

from yamljson.converter import ConversionError, json_to_yaml, yaml_to_json

try:
    json_to_yaml("data.json", "data.yaml")
    yaml_to_json("config.yaml", "config.json")
except ConversionError as exc:
    print(f"Conversion failed: {exc}")

Project Tree

yamljson/
├── LICENSE
├── README.md
├── pyproject.toml
├── tests/
│   ├── test_cli.py
│   └── test_converter.py
└── yamljson/
    ├── __init__.py
    ├── cli.py
    └── converter.py

How It Works

1. yamljson/cli.py parses CLI arguments.
2. It validates the file path and conversion target.
3. It routes the operation to:
   • json_to_yaml(...) or
   • yaml_to_json(...)
4. yamljson/converter.py reads input and writes converted output.

Error Cases and Notes

• Invalid JSON input raises ConversionError.
• Invalid YAML input raises ConversionError.
• YAML values not representable in JSON raise ConversionError.
• Output files are created in the same directory as the input file.
• Output filename is generated from the input basename:
  • name.json -> name.yaml
  • name.yaml -> name.json

Development

Install editable mode for local development:

pip install -e .

Run tests (if/when tests are added/expanded):

python -m pytest