---
product: Chilkat
product_version: 11.7.0
language: python
language_label: Python
document: language guide
---
> Chilkat 11.7.0 · language=python · this file: `https://www.chilkatsoft.com/ai-docs/v/11.7.0/python/guide.md`
> Class pages: `https://www.chilkatsoft.com/ai-docs/v/11.7.0/python/classes/<Class>.md`

# Chilkat for Python (chilkat2) — language guide — v11.7.0


## 1. Which Chilkat Python binding is this — and which to use

Chilkat ships **two** Python modules. They are the same library underneath (same classes, methods, properties, same version numbers) but have different Python spellings. **Do not mix them in one program.**

| | **chilkat2** (this guide) | **chilkat** ("CkPython", the original) |
|---|---|---|
| Install | `pip install chilkat2` | `pip install chilkat` |
| Import | `import chilkat2` | `import chilkat` |
| Class names | `chilkat2.Http`, `chilkat2.Zip`, `chilkat2.BinData` | `chilkat.CkHttp`, `chilkat.CkZip`, `chilkat.CkBinData` |
| Properties | plain attributes: `obj.Port = 993`, `s = obj.LastErrorText` | getters/setters: `obj.put_Port(993)`, `obj.lastErrorText()` |
| String-returning methods | one form: `s = http.QuickGetStr(url)` returns `str` | two forms: `http.QuickGetStr(url, ckStr)` → bool, or `http.quickGetStr(url)` → str |
| Binary data | any bytes-like in; read-only `memoryview` out | `bytes` in/out, `CkByteData` in older code |
| String method failure | returns `""` and `LastMethodSuccess` is `False` | `quickGetStr(url)` returns `None`; `QuickGetStr(url, ckStr)` returns `False` |

**For a new project use chilkat2.** If the developer's existing code uses `import chilkat` / `CkHttp` / `put_Xxx()`, that is CkPython — keep using it consistently; its reference is `https://www.chilkatsoft.com/ai-docs/v/11.7.0/ckpython/`.

## 2. Install and requirements

```
pip install chilkat2
```

One wheel per OS/CPU works with every CPython **3.7 and later** (the module targets the CPython stable ABI). Supported: Windows x64 / x86 / ARM64; Linux (glibc) x86_64 / aarch64 / armv7l; Alpine (musl) x86_64 / aarch64; macOS Apple silicon (macOS 11+) and Intel (macOS 10.14+). Python 3.6 and earlier and Python 2 are not supported. There are no other runtime dependencies — Chilkat has no dependency on OpenSSL, libcurl or any system library.

## 3. Unlocking (required in every program)

Call `Global.UnlockBundle` **once per process, before using any other class**:

```python
import chilkat2

glob = chilkat2.Global()
success = glob.UnlockBundle("Anything for 30-day trial")   # any string = 30-day trial; purchased code in production
if not success:
    print(glob.LastErrorText)
    raise SystemExit(1)
```

- Unlocking only sets a flag in memory: no license files, no network call, so it must be repeated each time the program runs.
- Extra calls are harmless no-ops. The `Global` object can be discarded after the call.
- If a program forgets to unlock, Chilkat silently runs in trial mode and stops working when the trial expires — so always include the call, and in production use the real unlock code.
- `UnlockBundle` unlocks every class. (Per-class `UnlockComponent` methods exist only in old code; use `UnlockBundle`.)

## 4. Error model — no exceptions; check the return value and `LastErrorText`

chilkat2 **never raises a Python exception for a Chilkat failure**. Exceptions occur only for Python-level misuse (wrong argument type or count). Every class has these members:

| Member | Meaning |
|---|---|
| `LastMethodSuccess` (bool) | Whether the most recent *method* call succeeded. Not changed by property get/set. |
| `LastErrorText` (str) | Multi-line diagnostic of the last method call — the first thing to print when something fails. Also populated on success. |
| `LastErrorXml`, `LastErrorHtml` | Same information, other formats. |
| `VerboseLogging` (bool) | Set `True` for more detail in `LastErrorText` while debugging. |
| `DebugLogFilePath` (str) | Set to a path to append every call's `LastErrorText` to a file. |
| `Version` (str) | Library version, e.g. `"11.7.0"`. |

How failure is reported depends on the method's return type — the class page states it per method (the "Returns … on failure" note under each method):

| Return type (refdoc form) | Python result | On failure |
|---|---|---|
| `bool` status method | `True` / `False` | returns `False`; read `LastErrorText` |
| `string` | `str` | returns `""` and `LastMethodSuccess` is `False` |
| `memoryview` | read-only `memoryview` | returns an empty (zero-length) memoryview; `LastMethodSuccess` is `False` |
| `int` | `int` | value may be valid or not — check `LastMethodSuccess` |
| object (e.g. `HttpResponse`) | the object | returns `None` |
| `void` | `None` | check `LastMethodSuccess` if needed |

Literals in Python: true is `True`, false is `False`, null/none is `None`.

Idiom:

```python
resp = chilkat2.HttpResponse()
success = http.HttpNoBody("GET", url, resp)   # bool status method; resp is filled in
if not success:
    print(http.LastErrorText)
    raise SystemExit(1)
print(resp.StatusCode, resp.BodyStr)
```

Many HTTP methods treat a response status ≥ 400 as failure (`False`/`None`) while still exposing the response — see each method's text. The last HTTP status is always in `http.LastStatus`.

## 5. Strings, bytes and encodings

- Strings are Python `str`. Chilkat works in UTF-8 internally; when a method takes a `charset` argument (e.g. `"utf-8"`, `"iso-8859-1"`) that is the encoding of the *bytes* being produced or interpreted, not of your Python `str`.
- Binary **in**: pass any bytes-like object (`bytes`, `bytearray`, `memoryview`).
- Binary **out**: methods and properties documented as `memoryview` return a **read-only memoryview** that is valid until the object is modified or freed. Copy it if you keep it: `data = bytes(mv)`.
- Larger or reusable binary data goes through `chilkat2.BinData` (methods ending in `Bd`), and text through `chilkat2.StringBuilder` (methods ending in `Sb`). Naming convention across the API: `Str` → Python `str`; `Bd` → BinData; `Sb` → StringBuilder; `File` → a file path.
- Method names with `2`/`3` suffixes or `Quick*` prefixes are distinct members, not overloads; Python keyword arguments are not supported — pass arguments positionally, in the documented order.

## 6. Object lifetime, threading, async

- Objects are ordinary Python objects; garbage collection frees them. Nothing needs explicit `Dispose`/`close`.
- A Chilkat object may be used from any thread, but **one object should not be used by two threads at the same time**. Create one object per thread or protect it with a lock.
- Every method whose class-page entry shows an "Async variant" line has an `XAsync` twin that takes the same arguments and immediately returns a `chilkat2.Task`. Pattern:

```python
task = http.QuickGetStrAsync(url)
if task is None:
    print(http.LastErrorText); raise SystemExit(1)
if not task.Run():
    print(task.LastErrorText); raise SystemExit(1)
while not task.Finished:
    task.SleepMs(100)              # or do other work; task.PercentDone, task.Cancel()
if task.TaskSuccess:
    s = task.GetResultString()
else:
    print(task.ResultErrorText)
```

No new Async methods are added from 11.7.0 on; a method introduced in 11.7.0 or later has no `Async` twin.

## 7. Callbacks / progress events

**Not available in chilkat2.** There is no event-callback object to subclass and no `EventCallbackObject` property. For progress, abort or percent-done, use the Async method + `Task` polling shown above. (CkPython, the other binding, does support callback objects.)

## 8. Common mistakes an AI makes with chilkat2

1. Writing CkPython spelling in a chilkat2 program: `chilkat2.CkHttp()`, `http.put_Port(443)`, `http.lastErrorText()`. In chilkat2 it is `chilkat2.Http()`, `http.Port = 443`, `http.LastErrorText`.
2. Wrapping Chilkat calls in `try/except` expecting a Chilkat failure to raise. It won't; check the return value.
3. Omitting `Global.UnlockBundle`.
4. Using deprecated methods still common in old examples: `PostJson`/`PostJson2`/`PostXml`/`PutText` → `HttpStr`; `PostJson3` → `HttpJson`; `PostUrlEncoded` → `HttpReq`; `QuickGetObj`/`QuickRequest`/`GetHead` → `HttpNoBody`; `PostBinary`/`PutBinary` → `HttpBinary`; `SynchronousRequest` → `HttpSReq`. The class page lists every deprecated member with its replacement.
5. Inventing members by analogy with other libraries (`http.get(...)`, `http.headers[...]`, `resp.json()`, `resp.text`). If a member is not on the class page, it does not exist — look it up rather than guessing.
6. Treating a `memoryview` result as `bytes` and holding it after the object changes — copy with `bytes(mv)`.
7. Passing Python `dict`s where a `chilkat2.JsonObject` is expected, or expecting a JSON method to return a `dict`. Chilkat JSON is `chilkat2.JsonObject` / `chilkat2.JsonArray`; use `json.Load(s)` / `json.Emit()` to convert to and from `str`.

## 9. Instructions block for coding agents

Paste into `CLAUDE.md`, `.cursor/rules`, or Copilot instructions:

```
This project uses Chilkat 11.7.0 for Python, the chilkat2 binding (pip install chilkat2; import chilkat2).
- Reference: https://www.chilkatsoft.com/ai-docs/v/11.7.0/python/ — read guide.md once, then classes/<Class>.md for each class used.
- Call chilkat2.Global().UnlockBundle(...) once at startup.
- Chilkat methods never raise on failure: check the bool/None/empty result and print obj.LastErrorText.
- Properties are attributes (obj.Port = 443); member names are PascalCase exactly as documented.
- Never use a member that is not on the class page; never use members listed as deprecated.
```

## 10. Classes

[Class index for Python](https://www.chilkatsoft.com/ai-docs/v/11.7.0/python/index.md)
