Caption format

Telegram-upload has a argument to add a message with every file you send. This is the caption argument. The caption argument (--caption "<message>") can be personalized for every file you send using variables between braces ({}). The variables are replaced with the corresponding value when the file is sent. The following variables are available:

  • {file}: file object. This variable has a lot of attributes available.

  • {now}: current datetime.

For example:

$ telegram-upload --caption "This is a file with name {file.name}" file.txt

The latest caption message will be “This is a file with name file.txt”. In case of using a invalid variable, the variable will be keep without replacing. The rest of variables will be replaced correctly. In case of a sintax error the entire caption will be keep without replacing.

The caption variables can be Python attributes of the {file} & {now} objects. Some methods without arguments are available too. In case of accesing to a unsupported method, the variable will be keep without replacing. The private attributes are prohibited for security reasons.

For testing the caption variables before sending the file, you can use the next command:

$ python -m telegram_upload.caption_formatter file.txt "{file.absolute}"

We recommend you to use the latest command to test the caption variables before sending the file.

If you need to use a brace in the caption, you can escape it using two braces. For example: {{ {file.name} }} will be replaced with { file.txt }.

The available attributes are described below.

Path attributes

The {file} variable has all the attributes of the pathlib.Path object. The following attributes are the most used:

  • {file.name}: file name with extension. For example file.txt.

  • {file.stem}: file name without extension. For example file.

  • {file.suffix}: file extension including the period. For example .txt.

  • {file.parent}: parent directory of the file. For example /home/user.

The next methods are available too:

  • {file.absolute}: absolute path of the file. For example /home/user/file.txt.

  • {file.home}: home directory of the user. For example /home/user.

The next methods are added or modified:

  • {file.relative}: relative path of the file. For example file.txt.

  • {file.mediatype}: media type of the file. For example text/plain.

  • {file.preffixes}: all preffixes of the file. For example .tar.gz for file.tar.gz.

The entire list of attributes and methods can be found in the pathlib.Path documentation

File size

The {file} variable has the {file.size} to get the file size. The size is returned in bytes. The size attribute has other attributes to get the size in other units. The following attributes are available:

  • {file.size}: file size in bytes.

  • {file.size.as_kibibytes}: file size in kibibytes (KiB).

  • {file.size.as_mebibytes}: file size in mebibytes (MiB).

  • {file.size.as_gibibytes}: file size in gibibytes (GiB).

  • {file.size.as_kilobytes}: file size in kilobytes (KB).

  • {file.size.as_megabytes}: file size in megabytes (MB).

  • {file.size.as_gigabytes}: file size in gigabytes (GB).

  • {file.size.for_humans}: file size in a human readable format. For example 1.2 MiB.

If you don’t know what is the difference between a kibibyte and a kilobyte, you can read the Wikipedia article about binary prefixes. We recommend to use the binary prefixes (KiB, MiB, GiB…) because they are the correct units for binary files.

Media attributes

The {file} variable has the {file.media} to get the media attributes. The media attributes are extracted from the video and audio files. The following attributes are available:

  • {file.media.width}: width of the video in pixels (only for video files).

  • {file.media.height}: height of the video in pixels (only for video files).

  • {file.media.title}: title of the media. This is extracted from the metadata of the file.

  • {file.media.artist}: artist of the media (only for audio files).

  • {file.media.album}: album of the media (only for audio files).

  • {file.media.producer}: producer of the media.

  • {file.media.duration}: duration of the media in seconds.

The duration attribute has other attributes to get the duration in other units. The following attributes are available:

  • {file.media.duration.as_minutes}: duration of the media in minutes.

  • {file.media.duration.as_hours}: duration of the media in hours.

  • {file.media.duration.as_days}: duration of the media in days.

  • {file.media.duration.for_humans}: duration of the media in a human readable format. For example 1 hour and 30 minutes. The text is in English.

Notice that some of the attributes will not be available if the file doesn’t have the metadata. Some video & audio doesn’t have the metadata. The metadata is extracted using the hachoir library

Datetime attributes

The file object has the following attributes to get the datetimes of the file:

  • {file.ctime}: datetime when the file was created.

  • {file.mtime}: datetime when the file was modified.

  • {file.atime}: datetime when the file was accessed.

By default the datetime is returned like YYYY-MM-DD HH:MM:SS.mmmmmm. The datetime attribute has other attributes to get the datetime in other formats. All the attributes from the datetime.datetime object are available. The following attributes are the most used:

  • {file.ctime.day}: day of the month. For example 1.

  • {file.ctime.month}: month of the year. For example 11.

  • {file.ctime.year}: year. For example 2019.

  • {file.ctime.hour}: hour of the day. For example 14.

  • {file.ctime.minute}: minute of the hour. For example 30.

  • {file.ctime.second}: second of the minute. For example 0.

The next methods are available too:

  • {file.ctime.astimezone}: datetime with timezone. For example 2019-11-01 14:30:00+01:00.

  • {file.ctime.ctime}: datetime in ctime format. For example Fri Nov  1 14:30:00 2019.

  • {file.ctime.date}: date in ISO 8601 format. For example 2019-11-01.

  • {file.ctime.dst}: dst of the tzinfo datetime.

  • {file.ctime.isoformat}: datetime in ISO 8601 format. For example 2019-11-01T14:30:00.123456.

  • {file.ctime.isoweekday}: day of the week. For example 5.

  • {file.ctime.now}: current datetime. For example 2023-06-29 02:32:15.123456.

  • {file.ctime.time}: time in ISO 8601 format. For example 14:30:00.123456.

  • {file.ctime.timestamp}: timestamp of the datetime. For example 1572622200.

  • {file.ctime.today}: current datetime. For example 2023-06-29 02:32:15.123456.

  • {file.ctime.toordinal}: ordinal of the datetime. For example 737373.

  • {file.ctime.tzname}: name of the timezone. For example CET.

  • {file.ctime.utcnow}: current datetime in UTC. For example 2019-11-01 13:30:00.123456.

  • {file.ctime.utcoffset}: offset of the timezone. For example 3600.

  • {file.ctime.weekday}: day of the week. For example 4.

The {file.mtime} and {file.atime} attributes have the same methods & attributes. Also the {now} variable.

For more info about the datetime attributes and methods, you can read the datetime.datetime documentation.

Checksum attributes

The file object has the following attributes to get the checksums of the file:

  • {file.md5}: MD5 checksum of the file. For example d41d8cd98f00b204e9800998ecf8427e.

  • {file.sha1}: SHA1 checksum of the file. For example da39a3ee5e6b4b0d3255bfef95601890afd80709.

  • {file.sha224}: SHA224 checksum of the file. For example d14a028c2a3a2bc9476102bb288234c415a2b01f828ea62ac5b3e42f.

  • {file.sha256}: SHA256 checksum of the file. For example e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855.

  • {file.sha384}: SHA384 checksum of the file.

  • {file.sha512}: SHA512 checksum of the file.

  • {file.sha3_224}: SHA3 224 checksum of the file.

  • {file.sha3_256}: SHA3 256 checksum of the file.

  • {file.sha3_384}: SHA3 384 checksum of the file.

  • {file.sha3_512}: SHA3 512 checksum of the file.

  • {file.crc32}: CRC32 checksum of the file. For example 00000000.

  • {file.adler32}: Adler32 checksum of the file. For example 00000001.

Note that the checksums are calculated after accesing the attribute. If you access the attribute twice, the checksum will be calculated twice. Calculate the checksums can take a lot of time, so it’s recommended to use the checksums only when you need them.

String methods

The next methods are available to manipulate the strings availables in the file object. All the examples are using the string attribute {file.stem} (with the value my file name), but you can use any string attribute.

  • {file.stem.title}: capitalize the string. For example My File Name.

  • {file.stem.capitalize}: capitalize the string. For example My file name.

  • {file.stem.lower}: convert the string to lowercase. For example my file name.

  • {file.stem.upper}: convert the string to uppercase. For example MY FILE NAME.

  • {file.stem.swapcase}: swap the case of the string. For example MY FILE NAME.

  • {file.stem.strip}: remove the leading and trailing characters. For example my file name. This is useful to remove the spaces in the filename. For example if the stem is `` my file name `` (with spaces), the value will be my file name.

  • {file.stem.lstrip}: remove the leading characters. For example my file name. Like strip but only remove the characters at the beginning of the string.

  • {file.stem.rstrip}: remove the trailing characters. For example my file name. Like strip but only remove the characters at the end of the string.