create

Convenience class used when creating a new torrent.

The TorrentCreate class provides some convenience fields that allows some common fields to be declared in a version-agnostic way at the top level, rather than nested within the infodict.

pydantic model TorrentCreate

A programmatically created torrent that may not have its hashes computed yet.

Torrents may be created either by passing an info dict with all details, (with or without piece hashes), or by using a handful of convenience fields. E.g. rather than needing to pass a fully instantiated file tree, one can just pass a list of files to files

Show JSON schema

{
   "title": "TorrentCreate",
   "description": "A programmatically created torrent that may not have its hashes computed yet.\n\nTorrents may be created *either* by passing an info dict with all details,\n(with or without piece hashes), *or* by using a handful of convenience fields.\nE.g. rather than needing to pass a fully instantiated file tree,\none can just pass a list of files to ``files``",
   "type": "object",
   "properties": {
      "announce": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Announce"
      },
      "announce-list": {
         "anyOf": [
            {
               "items": {
                  "items": {
                     "type": "string"
                  },
                  "type": "array"
               },
               "type": "array"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Announce-List"
      },
      "comment": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Comment"
      },
      "created by": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": "torrent-models (0.3.4.dev10+gf0da03c)",
         "title": "Created By"
      },
      "creation date": {
         "anyOf": [
            {
               "format": "date-time",
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Creation Date"
      },
      "info": {
         "$ref": "#/$defs/InfoDictHybridCreate"
      },
      "piece layers": {
         "anyOf": [
            {
               "additionalProperties": {
                  "items": {
                     "format": "binary",
                     "maxLength": 32,
                     "minLength": 32,
                     "type": "string"
                  },
                  "type": "array"
               },
               "propertyNames": {
                  "format": "binary",
                  "maxLength": 32,
                  "minLength": 32
               },
               "type": "object"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Piece Layers"
      },
      "url-list": {
         "anyOf": [
            {
               "items": {
                  "type": "string"
               },
               "type": "array"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "List of webseeds",
         "title": "Url-List"
      },
      "paths": {
         "anyOf": [
            {
               "items": {
                  "format": "path",
                  "type": "string"
               },
               "type": "array"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "\n        Convenience field for creating torrents from lists of files.\n        Can be either relative or absolute.\n        Paths must be located beneath the path root, passed either explicitly or using\n        cwd (default).\n        If absolute, paths are made relative to the path root.\n        ",
         "title": "Paths"
      },
      "path_root": {
         "description": "Path to interpret paths relative to",
         "format": "path",
         "title": "Path Root",
         "type": "string"
      },
      "trackers": {
         "anyOf": [
            {
               "items": {
                  "type": "string"
               },
               "type": "array"
            },
            {
               "items": {
                  "items": {
                     "type": "string"
                  },
                  "type": "array"
               },
               "type": "array"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Convenience method for declaring tracker lists.If a flat list, put each tracker in a separate tier.Otherwise, sublists indicate tiers.",
         "title": "Trackers"
      },
      "piece_length": {
         "anyOf": [
            {
               "type": "integer"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Convenience method for passing piece length",
         "title": "Piece Length"
      },
      "similar": {
         "anyOf": [
            {
               "items": {
                  "format": "binary",
                  "type": "string"
               },
               "type": "array"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Infohashes of other torrents that might contain overlapping files",
         "title": "Similar"
      }
   },
   "$defs": {
      "FileItem": {
         "additionalProperties": true,
         "properties": {
            "length": {
               "minimum": 0,
               "title": "Length",
               "type": "integer"
            },
            "path": {
               "items": {
                  "type": "string"
               },
               "title": "Path",
               "type": "array"
            },
            "attr": {
               "anyOf": [
                  {
                     "format": "binary",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Attr"
            }
         },
         "required": [
            "length",
            "path"
         ],
         "title": "FileItem",
         "type": "object"
      },
      "FileTreeItem": {
         "properties": {
            "length": {
               "title": "Length",
               "type": "integer"
            },
            "pieces root": {
               "format": "binary",
               "maxLength": 32,
               "minLength": 32,
               "title": "Pieces Root",
               "type": "string"
            }
         },
         "required": [
            "length"
         ],
         "title": "FileTreeItem",
         "type": "object"
      },
      "InfoDictHybridCreate": {
         "additionalProperties": true,
         "description": "An infodict of a hybrid torrent that may or may not have its pieces hashed yet",
         "properties": {
            "name": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Name"
            },
            "source": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Source"
            },
            "meta version": {
               "default": 2,
               "title": "Meta Version",
               "type": "integer"
            },
            "file tree": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/_FileTreeType"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null
            },
            "piece length": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Piece Length"
            },
            "pieces": {
               "anyOf": [
                  {
                     "items": {
                        "format": "binary",
                        "maxLength": 20,
                        "minLength": 20,
                        "type": "string"
                     },
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Pieces"
            },
            "length": {
               "anyOf": [
                  {
                     "minimum": 0,
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Length"
            },
            "files": {
               "anyOf": [
                  {
                     "items": {
                        "$ref": "#/$defs/FileItem"
                     },
                     "minItems": 1,
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Files"
            }
         },
         "title": "InfoDictHybridCreate",
         "type": "object"
      },
      "_FileTreeType": {
         "additionalProperties": {
            "anyOf": [
               {
                  "additionalProperties": {
                     "$ref": "#/$defs/FileTreeItem"
                  },
                  "propertyNames": {
                     "const": ""
                  },
                  "type": "object"
               },
               {
                  "$ref": "#/$defs/_FileTreeType"
               }
            ]
         },
         "propertyNames": {
            "format": "binary"
         },
         "type": "object"
      }
   },
   "additionalProperties": true
}

Config:

• populate_by_name: bool = True

• extra: str = allow

• validate_by_alias: bool = True

• validate_by_name: bool = True

Fields:

• announce (str | None)

• created_by (str | None)

• info (torrent_models.info.InfoDictHybridCreate)

• path_root (pathlib.Path)

• paths (list[pathlib.Path] | None)

• piece_length (int | None)

• similar (list[bytes] | None)

• trackers (list[str] | list[list[str]] | None)

Validators:

• name_from_path_root » all fields

• no_duplicated_params » all fields

field announce: Annotated[str, PlainSerializer(func=_to_bytes, return_type=PydanticUndefined, when_used=always)] | None = None

Validated by:

• name_from_path_root

• no_duplicated_params

field created_by: Annotated[str, PlainSerializer(func=_to_bytes, return_type=PydanticUndefined, when_used=always)] | None = 'torrent-models (0.3.4.dev10+gf0da03c)' (alias 'created by')

Validated by:

• name_from_path_root

• no_duplicated_params

field info: InfoDictHybridCreate [Optional]

Validated by:

• name_from_path_root

• no_duplicated_params

field path_root: Annotated[Path, AfterValidator(func=_is_abs)] [Optional]

Path to interpret paths relative to

Constraints:

• func = <function _is_abs at 0x70dff878dd00>

Validated by:

• name_from_path_root

• no_duplicated_params

field paths: list[Path] | None = None

Convenience field for creating torrents from lists of files. Can be either relative or absolute. Paths must be located beneath the path root, passed either explicitly or using cwd (default). If absolute, paths are made relative to the path root.

Validated by:

• name_from_path_root

• no_duplicated_params

field piece_length: Annotated[int, AfterValidator(func=_power_of_two)] | Annotated[int, AfterValidator(func=_divisible_by_16kib), AfterValidator(func=_power_of_two)] | None = None

Convenience method for passing piece length

Validated by:

• name_from_path_root

• no_duplicated_params

field similar: list[bytes] | None = None

Infohashes of other torrents that might contain overlapping files

Validated by:

• name_from_path_root

• no_duplicated_params

field trackers: list[Annotated[str, PlainSerializer(func=_to_bytes, return_type=PydanticUndefined, when_used=always)]] | list[list[Annotated[str, PlainSerializer(func=_to_bytes, return_type=PydanticUndefined, when_used=always)]]] | None = None

Convenience method for declaring tracker lists.If a flat list, put each tracker in a separate tier.Otherwise, sublists indicate tiers.

Validated by:

• name_from_path_root

• no_duplicated_params

generate(version: TorrentVersion | str, n_processes: int | None = 1, progress: bool = False) → Torrent

Generate a torrent file, hashing its pieces and transforming convenience values to valid torrent values.

generate_libtorrent(version: TorrentVersion | str, output: Path | None = None, bencode: bool = False, progress: bool = False) → dict | bytes

get_paths(clean: bool = True, v1_order: bool = False) → list[Path]

Get paths specified in one of potentially several ways

In order (first match is returned): - paths set in top level paths field - v2 file tree, if present - v1 files, if present - v1 name, if present with length set - iterate the files beneath the path_root

Parameters:

• clean (bool) – clean and sort the files

• v1_order (bool) – sort files in v1 order - first top-level files, then files in directories in case-sensitive alphanumeric order within those categories.

get_trackers() → TrackerFields

model_post_init(context: Any, /) → None

This function is meant to behave like a BaseModel method to initialise private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

• self – The BaseModel instance.

• context – The context.

validator name_from_path_root  »  all fields

If name is not provided, infer it from the path root

validator no_duplicated_params  »  all fields

Ensure that values that can be set from the top level convenience fields aren’t doubly set,

We don’t set the accompanying values in the infodict on instantiation because this object is intended to be a programmatic constructor object, so we expect these values to change and don’t want to have to worry about state consistency in it - all values are gathered and validated when the torrent is generated.

list_files(path: Path | str) → list[Path]

Recursively list files relative to path, sorting, excluding known system files

clean_files(paths: list[Path], relative_to: Path, v1: bool = False) → list[Path]

Remove system files, and make paths relative to some directory root