Filters¶

Created¶

class Created(days=0, hours=0, minutes=0, seconds=0, mode='older')¶

Matches files by created date

Parameters:

days (int) – specify number of days
hours (int) – specify number of hours
minutes (int) – specify number of minutes
mode (str) – either ‘older’ or ‘newer’. ‘older’ matches all files created before the given time, ‘newer’ matches all files created within the given time. (default = ‘older’)

Returns:

{created.year} – the year the file was created
{created.month} – the month the file was created
{created.day} – the day the file was created
{created.hour} – the hour the file was created
{created.minute} – the minute the file was created
{created.second} – the second the file was created

Examples:

Show all files on your desktop created at least 10 days ago:

config.yaml¶

rules:
  - folders: '~/Desktop'
    filters:
      - created:
          days: 10
    actions:
      - echo: 'Was created at least 10 days ago'

Show all files on your desktop which were created within the last 5 hours:

config.yaml¶

rules:
  - folders: '~/Desktop'
    filters:
      - created:
          hours: 5
          mode: newer
    actions:
      - echo: 'Was created within the last 5 hours'

Sort pdfs by year of creation:

config.yaml¶

rules:
  - folders: '~/Documents'
    filters:
      - extension: pdf
      - created
    actions:
      - move: '~/Documents/PDF/{created.year}/'

Exif¶

class Exif(*required_tags, **tag_filters)¶

Filter by image EXIF data

The exif filter can be used as a filter as well as a way to get exif information into your actions.

Returns:	`{exif}` – a dict of all the collected exif inforamtion available in the file. Typically it consists of the following tags (if present in the file): `{exif.image}` – information related to the main image `{exif.exif}` – Exif information `{exif.gps}` – GPS information `{exif.interoperability}` – Interoperability information

Examples:

Show available EXIF data of your pictures:

config.yaml¶

rules:
  - folders: ~/Pictures
    subfolders: true
    filters:
      - exif
    actions:
      - echo: "{exif}"

Copy all images which contain GPS information while keeping subfolder structure:

config.yaml¶

rules:
- folders: ~/Pictures
  subfolders: true
  filters:
    - exif:
        gps.gpsdate
  actions:
    - copy: ~/Pictures/with_gps/{relative_path}/

Filter by camera manufacturer:

config.yaml¶

rules:
  - folders: ~/Pictures
    subfolders: true
    filters:
      - exif:
          image.model: Nikon D3200
    actions:
      - move: '~/Pictures/My old Nikon/'

Sort images by camera manufacturer. This will create folders for each camera model (for example “Nikon D3200”, “iPhone 6s”, “iPhone 5s”, “DMC-GX80”) and move the pictures accordingly:

config.yaml¶

rules:
  - folders: ~/Pictures
    subfolders: true
    filters:
      - extension: jpg
      - exif:
          image.model
    actions:
      - move: '~/Pictures/{exif.image.model}/'

Extension¶

class Extension(*extensions)¶

Filter by file extension

Parameters:	extensions – The file extensions to match (does not need to start with a colon).
Returns:	`{extension}` – the original file extension (without colon) `{extension.lower}` – the file extension in lowercase `{extension.upper}` – the file extension in UPPERCASE

Examples:

Match a single file extension:

config.yaml¶

rules:
  - folders: '~/Desktop'
    filters:
      - extension: png
    actions:
      - echo: 'Found PNG file: {path}'

Match multiple file extensions:

config.yaml¶

rules:
  - folders: '~/Desktop'
    filters:
      - extension:
        - .jpg
        - jpeg
    actions:
      - echo: 'Found JPG file: {path}'

Make all file extensions lowercase:

config.yaml¶

rules:
  - folders: '~/Desktop'
    filters:
      - Extension
    actions:
      - rename: '{path.stem}.{extension.lower}'

Using extension lists:

config.yaml¶

img_ext: &img
  - png
  - jpg
  - tiff

audio_ext: &audio
  - mp3
  - wav
  - ogg

rules:
  - folders: '~/Desktop'
    filters:
      - extension:
        - *img
        - *audio
    actions:
      - echo: 'Found media file: {path}'

Filename¶

class Filename(startswith='', contains='', endswith='', case_sensitive=True)¶

Match files by filename

Parameters:	startswith (str) – The filename must begin with the given string contains (str) – The filename must contain the given string endswith (str) – The filename (without extension) must end with the given string case_sensitive = True (bool) – By default, the matching is case sensitive. Change this to False to use case insensitive matching.

Examples:

Match all files starting with ‘Invoice’:

config.yaml¶

rules:
  - folders: '~/Desktop'
    filters:
      - filename:
          startswith: Invoice
    actions:
      - echo: 'This is an invoice'

Match all files starting with ‘A’ end containing the string ‘hole’ (case insensitive)

config.yaml¶

rules:
  - folders: '~/Desktop'
    filters:
      - filename:
          startswith: A
          contains: hole
          case_sensitive: false
    actions:
      - echo: 'Found a match.'

Match all files starting with ‘A’ or ‘B’ containing ‘5’ or ‘6’ and ending with ‘_end’

config.yaml¶

rules:
  - folders: '~/Desktop'
    filters:
      - filename:
          startswith:
            - A
            - B
          contains:
            - 5
            - 6
          endswith: _end
          case_sensitive: false
    actions:
      - echo: 'Found a match.'

FileSize¶

class FileSize(*conditions)¶

Matches files by file size

Parameters:	conditions (str) –

Accepts file size conditions, e.g: '>= 500 MB', '< 20k', '>0', '= 10 KiB'.

It is possible to define both lower and upper conditions like this: '>20k, < 1 TB', '>= 20 Mb, <25 Mb'. The filter will match if all given conditions are satisfied.

Accepts all units from KB to YB.
If no unit is given, kilobytes are assumend.
If binary prefix is given (KiB, GiB) the size is calculated using base 1024.

Returns:	`{filesize.bytes}` – File size in bytes

Examples:

Trash big downloads:

config.yaml¶

rules:
  - folders: '~/Downloads'
    filters:
      - filesize: '> 0.5 GB'
    actions:
      - trash

Move all JPEGS bigger > 1MB and <10 MB. Search all subfolders and keep the´ original relative path.

config.yaml¶

rules:
  - folders: '~/Pictures'
    subfolders: true
    filters:
      - extension:
          - jpg
          - jpeg
      - filesize: '>1mb, <10mb'
    actions:
      - move: '~/Pictures/sorted/{relative_path}/'

LastModified¶

class LastModified(days=0, hours=0, minutes=0, seconds=0, mode='older')¶

Matches files by last modified date

Parameters:

days (int) – specify number of days
hours (int) – specify number of hours
minutes (int) – specify number of minutes
mode (str) – either ‘older’ or ‘newer’. ‘older’ matches all files last modified before the given time, ‘newer’ matches all files last modified within the given time. (default = ‘older’)

Returns:

{lastmodified.year} – the year the file was last modified
{lastmodified.month} – the month the file was last modified
{lastmodified.day} – the day the file was last modified
{lastmodified.hour} – the hour the file was last modified
{lastmodified.minute} – the minute the file was last modified
{lastmodified.second} – the second the file was last modified

Examples:

Show all files on your desktop last modified at least 10 days ago:

config.yaml¶

rules:
  - folders: '~/Desktop'
    filters:
      - lastmodified:
          days: 10
    actions:
      - echo: 'Was modified at least 10 days ago'

Show all files on your desktop which were modified within the last 5 hours:

config.yaml¶

rules:
  - folders: '~/Desktop'
    filters:
      - lastmodified:
          hours: 5
          mode: newer
    actions:
      - echo: 'Was modified within the last 5 hours'

Sort pdfs by year of last modification

config.yaml¶

rules:
  - folders: '~/Documents'
    filters:
      - extension: pdf
      - LastModified
    actions:
      - move: '~/Documents/PDF/{lastmodified.year}/'

Python¶

class Python(code)¶

Use python code to filter files.

Parameters:	code (str) – The python code to execute. The code must contain a `return` statement.
Returns:	If your code returns `False` or `None` the file is filtered out, otherwise the file is passed on to the next filters. `{python}` contains the returned value. If you return a dictionary (for example `return {"some_key": some_value, "nested": {"k": 2}}`) it will be accessible via dot syntax in your actions: `{python.some_key}`, `{python.nested.k}`.

Examples:

A file name reverser.

config.yaml¶

rules:
- folders: ~/Documents
  filters:
  - extension
  - python: |
      return {"reversed_name": path.stem[::-1]}
  actions:
  - rename: '{python.reversed_name}.{extension}'

A filter for odd student numbers. Assuming the folder ~/Students contains the files student-01.jpg, student-01.txt, student-02.txt and student-03.txt this rule will print "Odd student numbers: student-01.txt" and "Odd student numbers: student-03.txt"
config.yaml¶
```
rules:
- folders: ~/Students/
  filters:
   - python: |
     return int(path.stem.split('-')[1]) % 2 == 1
   actions:
   - echo: 'Odd student numbers: {path.name}'
```

Advanced usecase. You can access data from previous filters in your python code. This can be used to match files and capturing names with a regular expression and then renaming the files with the output of your python script.

config.yaml¶

rules:
  - folders: files
    filters:
      - extension: txt
      - regex: (?P<firstname>\w+)-(?P<lastname>\w+)\..*
      - python: |
          emails = {
              "Betts": "dbetts@mail.de",
              "Cornish": "acornish@google.com",
              "Bean": "dbean@aol.com",
              "Frey": "l-frey@frey.org",
          }
          if regex.lastname in emails: # get emails from wherever
              return {"mail": emails[regex.lastname]}
    actions:
      - rename: '{python.mail}.txt'

Result:

Devonte-Betts.txt becomes dbetts@mail.de.txt
Alaina-Cornish.txt becomes acornish@google.com.txt
Dimitri-Bean.txt becomes dbean@aol.com.txt
Lowri-Frey.txt becomes l-frey@frey.org.txt
Someunknown-User.txt remains unchanged because the email is not found

Regex¶

class Regex(expr)¶

Matches filenames with the given regular expression

Parameters:	expr (str) – The regular expression to be matched.

Any named groups in your regular expression will be returned like this:

Returns:	`{regex.yourgroupname}` – The text matched with the named group `(?P<yourgroupname>)`

Examples:

Match an invoice with a regular expression:

config.yaml¶

rules:
  - folders: '~/Desktop'
    filters:
      - regex: '^RG(\d{12})-sig\.pdf$'
    actions:
      - move: '~/Documents/Invoices/1und1/'

Match and extract data from filenames with regex named groups: This is just like the previous example but we rename the invoice using the invoice number extracted via the regular expression and the named group the_number.
config.yaml¶
```
rules:
  - folders: ~/Desktop
    filters:
      - regex: '^RG(?P<the_number>\d{12})-sig\.pdf$'
    actions:
      - move: ~/Documents/Invoices/1und1/{regex.the_number}.pdf
```