Metadata-Version: 2.4
Name: pyzwcadmech
Version: 0.2.0
Summary: A lightweight Python wrapper for ZWCAD Mechanical COM API
Home-page: https://github.com/john0909/pyzwcadmech
Author: John Zhang
Author-email: zhangxiang@zwcad.com
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: comtypes>=1.1.0
Dynamic: license-file

# pyzwcadmech Documentation

`pyzwcadmech` is a lightweight Python wrapper for the ZWCAD MFG COM API. It prefers dynamic COM calls first and uses the `ZwmToolKit` type library only as a compatibility enhancement when available.

For compatibility with recent changes, the distribution also includes the `pyzwcadm` package alias, while the primary package name is `pyzwcadmech`.

## 1. Requirements

- **OS**: Windows
- **Software Dependency**: A licensed installation of **ZWCAD MFG**
- **Python Environment**: Python 3.x
- **Third-party Libraries**: `comtypes`
  ```bash
  pip install comtypes
  ```
- **Type Library Note**: `ZwmToolKit.tlb` is optional. The library first tries to connect to the registered mechanical COM interfaces. If the type library is available, it can improve compatibility for a few complex calls.

## 2. Directory Structure

Recommended project layout:

```text
your_project_directory/
├── ZwmToolKit.tlb       # Optional COM type library for compatibility enhancement
├── pyzwcadmech/
│   ├── __init__.py
│   └── api.py
└── hello_mech.py
```

## 3. Quick Start

```python
from pyzwcadmech import ZwCADMech


def main():
    mech = ZwCADMech()
    mech.open_file("")

    title = mech.get_title()
    if title:
        print("Successfully obtained the title block object!")
        for i in range(title.get_item_count()):
            label, name, value = title.get_item(i)
            print(f"{label}: {value}")

    mech.close()


if __name__ == "__main__":
    main()
```

How to run the examples:

- Install dependencies: `pip install pyzwcadmech` and `pip install PyQt5`
- Install ZWCAD MFG on the machine
- Run a script from `examples`, for example `python pyqt_ZWM_example_en.py`
- In most cases you do not need to manually copy `ZwmToolKit.tlb`

## 4. API Reference

### 4.1 `ZwCADMech`

```python
mech = ZwCADMech(cad_app=None)
```

- `cad_app`: Optional existing `ZWCAD.Application` instance
- `mech.app`: Native `ZWCAD.Application` COM object
- `mech.zwm_app`: `ZwmApp` wrapper instance
- `mech.zwm_db`: `ZwmDb` wrapper instance

Shortcut methods delegated to `ZwmDb`:

- `open_file(filepath: str)`
- `save(flag: int = 33)`
- `close()`
- `get_title() -> ZwmTitle`
- `get_bom() -> ZwmBom`
- `get_frame() -> ZwmFrame`
- `title_edit()`, `total_bom_edit()`, `frame_edit()`, `fjl_edit()`

### 4.2 `ZwmTitle`

- `get_item_count() -> int`
- `get_item(index: int) -> tuple(str, str, str)`
- `set_item(key: str, value: str)`

### 4.3 `ZwmBom` and `ZwmBomRow`

`ZwmBom`:

- `get_item_count() -> int`
- `get_item(index: int) -> ZwmBomRow`
- `set_item(index: int, bom_row: ZwmBomRow)`
- `add_item(bom_row: ZwmBomRow)`
- `insert_item(index: int, bom_row: ZwmBomRow)`
- `delete_item(index: int)`
- `create_bom_row() -> ZwmBomRow`

`ZwmBomRow`:

- `get_item_count() -> int`
- `get_item(index: int) -> tuple(str, str, str)`
- `set_item(key: str, value: str)`

### 4.4 `ZwmFrame`

`ZwmFrame` exposes frame properties directly through Python properties, including:

- `width`, `height`, `std_name`, `frame_size_name`, `orientation`, `scale1`, `scale2`
- `frame_style_name`, `title_style_name`, `bom_style_name`, `dhl_style_name`, `fjl_style_name`, `csl_style_name`, `ggl_style_name`
- `have_dhl`, `have_fjl`, `have_btl`, `have_csl`, `have_ggl`

After editing properties, call `mech.zwm_db.build_frame(511)` or `refresh_frame()` to apply the changes.

### 4.5 `ZwmDb`

Additional database methods:

- `switch_frame(frame_name: str)`
- `get_frame_count() -> int`
- `get_frame_name(index: int) -> str`
- `get_next_frm_name() -> tuple(ZwmFrame, str)`
- `refresh_title()`, `refresh_bom()`, `refresh_frame()`
- `build_frame(switch_type: int = 511)`

## 5. FAQ

**Q: Do I need `ZwmToolKit.tlb` to use the library?**  
A: Usually no. `pyzwcadmech` now prefers dynamic COM calls first. The type library is mainly used to improve compatibility for a few complex interface calls.

**Q: I see `Failed to load ZwmToolKit.tlb` or `ModuleNotFoundError`.**  
A: First make sure `comtypes` is installed and try connecting to ZWCAD MFG directly. If only a few complex calls fail, then add `ZwmToolKit.tlb` to your project directory or set `PYZWCADMECH_TLB_PATH`.

**Q: I see `Failed to create ZwmToolKit.ZwmApp`.**  
A: This usually means either the standard ZWCAD edition is installed instead of the Mechanical edition, or the mechanical COM component is not registered correctly.

**Q: `get_title()` or `get_bom()` returns `None` or raises an error.**  
A: Make sure `mech.open_file("")` was called successfully and that the current drawing actually contains the corresponding mechanical entities.

## 6. Packaging and Release

Recommended modern build flow:

```bash
python -m pip install --upgrade build twine
python -m build
python -m twine check dist/*
python -m twine upload dist/*
```
