Skip to content

Commit

Permalink
added feature --download-media-name to select a method for naming med…
Browse files Browse the repository at this point in the history 
…ia files that are downloaded

- minor updates to doc
  • Loading branch information
8go committed Oct 10, 2023
1 parent 5ad8769 commit 25845fb
Show file tree
Hide file tree
Showing 11 changed files with 166 additions and 33 deletions.
41 changes: 30 additions & 11 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -247,7 +247,7 @@ be performed fully in batch.

Since the credentials file holds an access token it
should be protected and secured. One can use different
credential files for different users or different rooms.
credential files for different users (or different default rooms).

On creation the credentials file will by default be created in the local
directory, so the users sees it right away. This is fine if you have
Expand Down Expand Up @@ -647,7 +647,7 @@ $ matrix-commander --room-redact \
'\!someroomId2:example.com' '\$someEventId2' 'Image deleted, outdated'
$ # list room invitations
$ matrix-commander --listen once --room-invites list
$ # accepting room invitations, automatically joining rooms to which one is
$ # accepting room invitations, automatically joining rooms to which one is
$ # invited to
$ matrix-commander --listen forever --room-invites list+join
$ # print its own user id
Expand Down Expand Up @@ -797,8 +797,9 @@ usage: matrix-commander [--usage] [-h] [--manual] [--readme] [-d]
[--proxy PROXY] [-n] [--encrypted]
[-l [NEVER|ONCE|FOREVER|TAIL|ALL]] [-t [NUMBER]] [-y]
[--print-event-id]
[--download-media [DOWNLOAD_DIRECTORY]] [--os-notify]
[--set-device-name DEVICE_NAME]
[--download-media [DOWNLOAD_DIRECTORY]]
[--download-media-name SOURCE|CLEAN|EVENTID]
[--os-notify] [--set-device-name DEVICE_NAME]
[--set-display-name DISPLAY_NAME] [--get-display-name]
[--set-presence ONLINE|OFFLINE|UNAVAILABLE]
[--get-presence] [--upload FILE [FILE ...]]
Expand Down Expand Up @@ -1342,12 +1343,30 @@ options:
Download media files while listening. Details:: If set
and listening, then program will download received
media files (e.g. image, audio, video, text, PDF
files). media will be downloaded to local directory.
By default, media will be downloaded to is "./media/".
You can overwrite default with your preferred
directory. If media is encrypted it will be decrypted
and stored decrypted. By default media files will not
be downloaded.
files). By default, media will be downloaded to this
directory: "./media/". You can overwrite default with
your preferred directory. If you provide a relative
path, the relative path will be relative to the local
directory. foo will become ./foo. foo/foo will become
./foo/foo and only works if ./foo already exists.
Absolute paths will remein unchanged. /tmp will remain
/tmp. /tmp/foo will be /tmp/foo. If media is encrypted
it will be decrypted and stored decrypted. By default
media files will not be downloaded.
--download-media-name SOURCE|CLEAN|EVENTID
Specify the method to derive the media filename.
Details:: This argument is optional. Currently three
choices are offered: 'source', 'clean' and 'eventid'.
'source' means the value specified by the source
(sender) will be used. If the sender, i.e. source,
specifies a value that is not a valid filename, then a
failure will occur and the media file will not be
saved. 'clean' means that all dangerous characters in
the name provided by the source will be replaced by an
underscore to create a valid file name. 'eventid'
means that the name provided by the source will be
ignored and the event-id will be used instead. If not
specified it defaults to 'clean'.
--os-notify Notify me of arriving messages. Details:: If set and
listening, then program will attempt to visually
notify of arriving messages through the operating
Expand Down Expand Up @@ -1870,7 +1889,7 @@ options:
the program will continue to run. This is useful for
having version number in the log files.
You are running version 7.2.0 2023-04-20. Enjoy, star on Github and contribute
You are running version 7.3.0 2023-10-10. Enjoy, star on Github and contribute
by submitting a Pull Request. Also have a look at matrix-commander-tui.
```

Expand Down
2 changes: 1 addition & 1 deletion VERSION
View file
Original file line number Diff line number Diff line change
@@ -1 +1 @@
7.2.0
7.3.0
Binary file removed dist/matrix-commander-7.2.0.tar.gz
View file
Binary file not shown.
Binary file added dist/matrix-commander-7.3.0.tar.gz
View file
Binary file not shown.
Binary file removed dist/matrix_commander-7.2.0-py3-none-any.whl
View file
Binary file not shown.
Binary file added dist/matrix_commander-7.3.0-py3-none-any.whl
View file
Binary file not shown.
4 changes: 3 additions & 1 deletion help.help.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -98,6 +98,8 @@ matrix-commander supports these arguments:
Print event ids of received messages.
--download-media [DOWNLOAD_DIRECTORY]
Download media files while listening.
--download-media-name SOURCE|CLEAN|EVENTID
Specify the method to derive the media filename.
--os-notify
Notify me of arriving messages.
--set-device-name DEVICE_NAME
Expand Down Expand Up @@ -200,5 +202,5 @@ delete-content ROOM_ID EVENT_ID REASON [ROOM_ID EVENT_ID REASON ...]
-v [PRINT|CHECK], -V [PRINT|CHECK], --version [PRINT|CHECK]
Print version information or check for updates.

You are running version 7.2.0 2023-04-20. Enjoy, star on Github and contribute
You are running version 7.3.0 2023-10-10. Enjoy, star on Github and contribute
by submitting a Pull Request. Also have a look at matrix-commander-tui.
37 changes: 28 additions & 9 deletions help.manual.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -43,8 +43,9 @@ usage: matrix-commander [--usage] [-h] [--manual] [--readme] [-d]
[--proxy PROXY] [-n] [--encrypted]
[-l [NEVER|ONCE|FOREVER|TAIL|ALL]] [-t [NUMBER]] [-y]
[--print-event-id]
[--download-media [DOWNLOAD_DIRECTORY]] [--os-notify]
[--set-device-name DEVICE_NAME]
[--download-media [DOWNLOAD_DIRECTORY]]
[--download-media-name SOURCE|CLEAN|EVENTID]
[--os-notify] [--set-device-name DEVICE_NAME]
[--set-display-name DISPLAY_NAME] [--get-display-name]
[--set-presence ONLINE|OFFLINE|UNAVAILABLE]
[--get-presence] [--upload FILE [FILE ...]]
Expand Down Expand Up @@ -588,12 +589,30 @@ options:
Download media files while listening. Details:: If set
and listening, then program will download received
media files (e.g. image, audio, video, text, PDF
files). media will be downloaded to local directory.
By default, media will be downloaded to is "./media/".
You can overwrite default with your preferred
directory. If media is encrypted it will be decrypted
and stored decrypted. By default media files will not
be downloaded.
files). By default, media will be downloaded to this
directory: "./media/". You can overwrite default with
your preferred directory. If you provide a relative
path, the relative path will be relative to the local
directory. foo will become ./foo. foo/foo will become
./foo/foo and only works if ./foo already exists.
Absolute paths will remein unchanged. /tmp will remain
/tmp. /tmp/foo will be /tmp/foo. If media is encrypted
it will be decrypted and stored decrypted. By default
media files will not be downloaded.
--download-media-name SOURCE|CLEAN|EVENTID
Specify the method to derive the media filename.
Details:: This argument is optional. Currently three
choices are offered: 'source', 'clean' and 'eventid'.
'source' means the value specified by the source
(sender) will be used. If the sender, i.e. source,
specifies a value that is not a valid filename, then a
failure will occur and the media file will not be
saved. 'clean' means that all dangerous characters in
the name provided by the source will be replaced by an
underscore to create a valid file name. 'eventid'
means that the name provided by the source will be
ignored and the event-id will be used instead. If not
specified it defaults to 'clean'.
--os-notify Notify me of arriving messages. Details:: If set and
listening, then program will attempt to visually
notify of arriving messages through the operating
Expand Down Expand Up @@ -1116,5 +1135,5 @@ options:
the program will continue to run. This is useful for
having version number in the log files.

You are running version 7.2.0 2023-04-20. Enjoy, star on Github and contribute
You are running version 7.3.0 2023-10-10. Enjoy, star on Github and contribute
by submitting a Pull Request. Also have a look at matrix-commander-tui.
7 changes: 4 additions & 3 deletions help.usage.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,8 +25,9 @@ usage: matrix-commander [--usage] [-h] [--manual] [--readme] [-d]
[--proxy PROXY] [-n] [--encrypted]
[-l [NEVER|ONCE|FOREVER|TAIL|ALL]] [-t [NUMBER]] [-y]
[--print-event-id]
[--download-media [DOWNLOAD_DIRECTORY]] [--os-notify]
[--set-device-name DEVICE_NAME]
[--download-media [DOWNLOAD_DIRECTORY]]
[--download-media-name SOURCE|CLEAN|EVENTID]
[--os-notify] [--set-device-name DEVICE_NAME]
[--set-display-name DISPLAY_NAME] [--get-display-name]
[--set-presence ONLINE|OFFLINE|UNAVAILABLE]
[--get-presence] [--upload FILE [FILE ...]]
Expand Down Expand Up @@ -63,5 +64,5 @@ usage: matrix-commander [--usage] [-h] [--manual] [--readme] [-d]
[--room-invites [LIST|JOIN|LIST+JOIN]]
[-v [PRINT|CHECK]]

You are running version 7.2.0 2023-04-20. Enjoy, star on Github and contribute
You are running version 7.3.0 2023-10-10. Enjoy, star on Github and contribute
by submitting a Pull Request. Also have a look at matrix-commander-tui.
106 changes: 99 additions & 7 deletions matrix_commander/matrix_commander.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -94,8 +94,8 @@
HAVE_OPENID = False

# version number
VERSION = "2023-04-20"
VERSIONNR = "7.2.0"
VERSION = "2023-10-10"
VERSIONNR = "7.3.0"
# matrix-commander; for backwards compitability replace _ with -
PROG_WITHOUT_EXT = os.path.splitext(os.path.basename(__file__))[0].replace(
"_", "-"
Expand Down Expand Up @@ -181,6 +181,15 @@
# adhere to Spec and hence print a JSON object. All other print nothing.
OUTPUT_JSON_SPEC = "json-spec"
OUTPUT_DEFAULT = OUTPUT_TEXT

# source, as provided by sender
MEDIA_NAME_SOURCE = "source"
# cleaned up. Source but with dangeraous chars replaced with _
MEDIA_NAME_CLEAN = "clean"
# use event-id as media file name
MEDIA_NAME_EVENTID = "eventid"
MEDIA_NAME_DEFAULT = MEDIA_NAME_CLEAN

# location of README.md file if it is not found on local harddisk
# used for --manual
README_FILE_RAW_URL = (
Expand Down Expand Up @@ -722,8 +731,26 @@ async def message_callback(self, room: MatrixRoom, event): # noqa: C901
msg_url += " [Download of media file failed]"
else:
media_data = resp.body
method = gs.pa.download_media_name
if method == MEDIA_NAME_SOURCE:
newfn = event.body
elif method == MEDIA_NAME_EVENTID:
newfn = event.event_id
else:
# event.body is not trustworthy
# and can contain garbage characters
# such as / or \ which will cause file open
# to fail. Replace those.
newfn = "".join(
[
x if (x.isalnum() or x in "._- ~") else "_"
for x in event.body
]
)
gs.log.debug(f"Media file name method is : {method}")
gs.log.debug(f"New file name for media is : {newfn}")
filename = choose_available_filename(
os.path.join(gs.pa.download_media, event.body)
os.path.join(gs.pa.download_media, newfn)
)
async with aiofiles.open(filename, "wb") as f:
await f.write(media_data)
Expand Down Expand Up @@ -752,8 +779,26 @@ async def message_callback(self, room: MatrixRoom, event): # noqa: C901
msg_url += " [Download of media file failed]"
else:
media_data = resp.body
method = gs.pa.download_media_name
if method == MEDIA_NAME_SOURCE:
newfn = event.body
elif method == MEDIA_NAME_EVENTID:
newfn = event.event_id
else:
# event.body is not trustworthy
# and can contain garbage characters
# such as / or \ which will cause file open
# to fail. Replace those.
newfn = "".join(
[
x if (x.isalnum() or x in "._- ~") else "_"
for x in event.body
]
)
gs.log.debug(f"Media file name method is : {method}")
gs.log.debug(f"New file name for media is : {newfn}")
filename = choose_available_filename(
os.path.join(gs.pa.download_media, event.body)
os.path.join(gs.pa.download_media, newfn)
)
async with aiofiles.open(filename, "wb") as f:
await f.write(
Expand Down Expand Up @@ -6509,6 +6554,8 @@ def initial_check_of_args() -> None: # noqa: C901
gs.pa.sync = gs.pa.sync.lower()
if gs.pa.output is not None:
gs.pa.output = gs.pa.output.lower()
if gs.pa.download_media_name is not None:
gs.pa.download_media_name = gs.pa.download_media_name.lower()
if gs.pa.room_invites:
gs.pa.room_invites = gs.pa.room_invites.lower()

Expand Down Expand Up @@ -6757,6 +6804,23 @@ def initial_check_of_args() -> None: # noqa: C901
"either. Specify --listen or --tail "
f"and run program again. ({gs.pa.download_media})"
)
elif gs.pa.download_media_name != "" and (not gs.pa.download_media):
t = (
"If --download-media is not used, "
"then --download-media-name must not be used "
"either. Specify --download-media "
f"and run program again. ({gs.pa.download_media_name})"
)
elif gs.pa.download_media_name not in (
MEDIA_NAME_SOURCE,
MEDIA_NAME_CLEAN,
MEDIA_NAME_EVENTID,
):
t = (
"Incorrect value given for --download-media-name. "
f"Only '{MEDIA_NAME_SOURCE}', '{MEDIA_NAME_CLEAN}', "
f"'{MEDIA_NAME_EVENTID}' are allowed."
)
elif gs.pa.listen == TAIL and (gs.pa.tail <= 0):
t = (
"An integer 1 or larger must be specified with --tail "
Expand Down Expand Up @@ -7769,13 +7833,39 @@ def main_inner(
"Details:: If set and listening, "
"then program will download "
"received media files (e.g. image, audio, video, text, PDF files). "
"media will be downloaded to local directory. "
"By default, media will be downloaded to "
f'is "{MEDIA_DIR_DEFAULT}". '
"By default, media will be downloaded to this directory: "
f'"{MEDIA_DIR_DEFAULT}". '
"You can overwrite default with your preferred directory. "
"If you provide a relative path, the relative path will be relative "
"to the local directory. foo will become ./foo. "
"foo/foo will become ./foo/foo and only works if ./foo already "
"exists. "
"Absolute paths will remein unchanged. /tmp will remain /tmp. "
"/tmp/foo will be /tmp/foo. "
"If media is encrypted it will be decrypted and stored decrypted. "
"By default media files will not be downloaded.",
)
ap.add_argument(
"--download-media-name",
required=False,
default=MEDIA_NAME_DEFAULT,
type=str, # method to derive filename
metavar="SOURCE|CLEAN|EVENTID",
help="Specify the method to derive the media filename. "
"Details:: This argument is optional. "
"Currently three choices are offered: 'source', 'clean' and "
"'eventid'. "
"'source' means the value specified by the source (sender) "
"will be used. If the sender, i.e. source, specifies a value "
"that is not a valid filename, then a failure will occur and "
"the media file will not be saved. "
"'clean' means that all dangerous characters in the name "
"provided by the source will be replaced "
"by an underscore to create a valid file name. "
"'eventid' means that the name provided by the source will be "
"ignored and the event-id will be used instead. "
f"If not specified it defaults to '{MEDIA_NAME_DEFAULT}'. ",
)
ap.add_argument(
# "-o", # incompatible change Dec 2022, -o moved to --output
"--os-notify",
Expand Down Expand Up @@ -8783,6 +8873,8 @@ def main_inner(
Print event ids of received messages.
<--download-media> [DOWNLOAD_DIRECTORY]
Download media files while listening.
<--download-media-name> SOURCE|CLEAN|EVENTID
Specify the method to derive the media filename.
<--os-notify>
Notify me of arriving messages.
<--set-device-name> DEVICE_NAME
Expand Down
2 changes: 1 addition & 1 deletion setup.cfg
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
# https://packaging.python.org/en/latest/tutorials/packaging-projects/
# https://setuptools.pypa.io/en/latest/userguide/
name = matrix-commander
version = 7.2.0
version = 7.3.0
author = 8go
description = A simple command-line Matrix client
long_description = file: PyPi-Instructions.md, README.md
Expand Down

0 comments on commit 25845fb

Please sign in to comment.