# ipyfilechooser
A simple Python file chooser widget for use in Jupyter/IPython in conjunction with ipywidgets. The selected path and file are available via `.selected_path` and `.selected_filename` respectvely or as a single combined filepath via `.selected`. The dialog can be reset to its default path and filename by using `.reset()`.
When a typed filename matches an existing file entry in the current folder the entry will be highlighted. If a typed filename matches a folder entry in the current view the selection button is disabled ensure the user is aware of the match. To select a folder simply leave the filename field empty.
To emphasize the risk of overwriting existing files, the selected filepath is displayed in green if the file does not exist and orange if it does.
[](https://pepy.tech/project/ipyfilechooser)
## Usage
```python
from ipyfilechooser import FileChooser
# Create and display a FileChooser widget
fc = FileChooser('/Users/crahan/FC demo')
display(fc)
# Print the selected path, filename, or both
print(fc.selected_path)
print(fc.selected_filename)
print(fc.selected)
# Change defaults and reset the dialog
fc.default_path = '/Users/crahan/'
fc.default_filename = 'output.txt'
fc.reset()
# Shorthand reset
fc.reset(path='/Users/crahan/', filename='output.txt')
# Restrict navigation to /Users
fc.sandbox_path = '/Users'
# Change hidden files
fc.show_hidden = True
# Customize dir icon
fc.dir_icon = '/'
fc.dir_icon_append = True
# Switch to folder-only mode
fc.show_only_dirs = True
# Set a file filter pattern (uses https://docs.python.org/3/library/fnmatch.html)
fc.filter_pattern = '*.txt'
# Set multiple file filter patterns (uses https://docs.python.org/3/library/fnmatch.html)
fc.filter_pattern = ['*.jpg', '*.png']
# Change the title (use '' to hide)
fc.title = '<b>FileChooser title</b>'
# Sample callback function
def change_title(chooser):
chooser.title = '<b>Callback function executed</b>'
# Register callback function
fc.register_callback(change_title)
```
## Functions and properties
```python
fc.reset()
fc.refresh()
fc.register_callback(function_name)
fc.show_hidden
fc.dir_icon
fc.dir_icon_append
fc.show_only_dirs
fc.rows
fc.title
fc.filter_pattern
fc.default
fc.default_path
fc.default_filename
fc.sandbox_path
fc.value
fc.selected
fc.selected_path
fc.selected_filename
```
## Screenshots
### Closed vs open dialog
### Existing vs new file selection
### Quick navigation dropdown
### Use folder icons
### Restrict navigation
## Release notes
### 0.6.0
- The ability to restrict file browsing to a `sandbox_path` folder has finally been added!
- Filenames can not contain path separator characters or parent folder strings (i.e., '..')
- `use_dir_icons` has been replaced with `dir_icon` which allows for customizing the folder icon
- `dir_icon_append` can now be used to put the folder icon before or after the folder name
- Better error handling with `ParentPathError`, `InvalidPathError`, and `InvalidFileNameError`
- Better and more consistent handling of Windows drive letters and paths
- Fix bug where resetting the filechooser would not reenable the select/change button
- Properly handle folder permission errors by raising a warning
### 0.5.0
- Widget width is now configurable using the `layout` property and a `Layout` object
- Folder paths are now normalized using `os.path.normpath` to properly handle '/' and '\\' on Windows
- The widget now supports the `value` property to align with other widget types
- The label showing the selected value now reflows the text to new lines as required (and shows a scrollbar if the value is too long)
- Buttons now have a minimum width to ensure their text is always visible, regardless of widget width
### 0.4.4
- Added typing hints (@Mandroide)
- Updated max line length check from 90 to 120 characters
- Fixed `filter_pattern` values not being treated as case-insensitive
- General code cleanup
### 0.4.3
- Prevent applying the selected value if the filename doesn't match one of the `filter_pattern` values
### 0.4.2
- Added ability to specify a list of `fnmatch` pattern strings for `filter_pattern`
### 0.4.1
- Fixed issue with `select_default` not being applied on `reset`
### 0.4.0
- Option added to specify a file filter (@andriykorchak)
- Add support for `ValueWidget` and `get_interact_value()`
- Updated sample notebook with filter example
- Updated Development Status to Production/Stable
### 0.3.5
- Option added to only display folders (@andriykorchak)
### 0.3.4
- Option added to display folder icons (@ptooley)
### 0.3.3
- Option added to add `self` as an argument to the callback function (@ptooley)
### 0.3.2
- Return `None` if file is not selected (@danjjl)
### 0.3.1
- Option to register a callback function (`register_callback(function_name)`)
### 0.3.0
- Ability to select a folder
- Support for Windows drive letters
- Option to use the defaults as the selected value
### 0.2.0
- First public release
Raw data
{
"_id": null,
"home_page": "https://github.com/crahan/ipyfilechooser",
"name": "ipyfilechooser",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Thomas Bouve (@crahan)",
"author_email": "crahan@n00.be",
"download_url": "https://files.pythonhosted.org/packages/13/63/a0bfdda0cdf002421632734e203e4692d72dc4e71cd006f101c90f9ba6d3/ipyfilechooser-0.6.0.tar.gz",
"platform": "",
"description": "# ipyfilechooser\n\nA simple Python file chooser widget for use in Jupyter/IPython in conjunction with ipywidgets. The selected path and file are available via `.selected_path` and `.selected_filename` respectvely or as a single combined filepath via `.selected`. The dialog can be reset to its default path and filename by using `.reset()`. \n\nWhen a typed filename matches an existing file entry in the current folder the entry will be highlighted. If a typed filename matches a folder entry in the current view the selection button is disabled ensure the user is aware of the match. To select a folder simply leave the filename field empty.\n\nTo emphasize the risk of overwriting existing files, the selected filepath is displayed in green if the file does not exist and orange if it does. \n\n[](https://pepy.tech/project/ipyfilechooser)\n\n## Usage\n\n```python\nfrom ipyfilechooser import FileChooser\n\n# Create and display a FileChooser widget\nfc = FileChooser('/Users/crahan/FC demo')\ndisplay(fc)\n\n# Print the selected path, filename, or both\nprint(fc.selected_path)\nprint(fc.selected_filename)\nprint(fc.selected)\n\n# Change defaults and reset the dialog\nfc.default_path = '/Users/crahan/'\nfc.default_filename = 'output.txt'\nfc.reset()\n\n# Shorthand reset\nfc.reset(path='/Users/crahan/', filename='output.txt')\n\n# Restrict navigation to /Users\nfc.sandbox_path = '/Users'\n\n# Change hidden files\nfc.show_hidden = True\n\n# Customize dir icon\nfc.dir_icon = '/'\nfc.dir_icon_append = True\n\n# Switch to folder-only mode\nfc.show_only_dirs = True\n\n# Set a file filter pattern (uses https://docs.python.org/3/library/fnmatch.html)\nfc.filter_pattern = '*.txt'\n\n# Set multiple file filter patterns (uses https://docs.python.org/3/library/fnmatch.html)\nfc.filter_pattern = ['*.jpg', '*.png']\n\n# Change the title (use '' to hide)\nfc.title = '<b>FileChooser title</b>'\n\n# Sample callback function\ndef change_title(chooser):\n chooser.title = '<b>Callback function executed</b>'\n\n# Register callback function\nfc.register_callback(change_title)\n```\n\n## Functions and properties\n\n```python\nfc.reset()\nfc.refresh()\nfc.register_callback(function_name)\nfc.show_hidden\nfc.dir_icon\nfc.dir_icon_append\nfc.show_only_dirs\nfc.rows\nfc.title\nfc.filter_pattern\nfc.default\nfc.default_path\nfc.default_filename\nfc.sandbox_path\nfc.value\nfc.selected\nfc.selected_path\nfc.selected_filename\n```\n\n## Screenshots\n\n### Closed vs open dialog\n\n\n\n\n\n### Existing vs new file selection\n\n\n\n\n\n### Quick navigation dropdown\n\n\n\n### Use folder icons\n\n\n\n### Restrict navigation\n\n\n\n## Release notes\n\n### 0.6.0\n\n- The ability to restrict file browsing to a `sandbox_path` folder has finally been added!\n- Filenames can not contain path separator characters or parent folder strings (i.e., '..')\n- `use_dir_icons` has been replaced with `dir_icon` which allows for customizing the folder icon\n- `dir_icon_append` can now be used to put the folder icon before or after the folder name\n- Better error handling with `ParentPathError`, `InvalidPathError`, and `InvalidFileNameError`\n- Better and more consistent handling of Windows drive letters and paths\n- Fix bug where resetting the filechooser would not reenable the select/change button\n- Properly handle folder permission errors by raising a warning\n\n### 0.5.0\n\n- Widget width is now configurable using the `layout` property and a `Layout` object\n- Folder paths are now normalized using `os.path.normpath` to properly handle '/' and '\\\\' on Windows\n- The widget now supports the `value` property to align with other widget types\n- The label showing the selected value now reflows the text to new lines as required (and shows a scrollbar if the value is too long)\n- Buttons now have a minimum width to ensure their text is always visible, regardless of widget width\n\n### 0.4.4\n\n- Added typing hints (@Mandroide)\n- Updated max line length check from 90 to 120 characters\n- Fixed `filter_pattern` values not being treated as case-insensitive\n- General code cleanup\n\n### 0.4.3\n\n- Prevent applying the selected value if the filename doesn't match one of the `filter_pattern` values\n\n### 0.4.2\n\n- Added ability to specify a list of `fnmatch` pattern strings for `filter_pattern`\n\n### 0.4.1\n\n- Fixed issue with `select_default` not being applied on `reset`\n\n### 0.4.0\n\n- Option added to specify a file filter (@andriykorchak)\n- Add support for `ValueWidget` and `get_interact_value()`\n- Updated sample notebook with filter example\n- Updated Development Status to Production/Stable\n\n### 0.3.5\n\n- Option added to only display folders (@andriykorchak)\n\n### 0.3.4\n\n- Option added to display folder icons (@ptooley)\n\n### 0.3.3\n\n- Option added to add `self` as an argument to the callback function (@ptooley)\n\n### 0.3.2\n\n- Return `None` if file is not selected (@danjjl)\n\n### 0.3.1\n\n- Option to register a callback function (`register_callback(function_name)`)\n\n### 0.3.0\n\n- Ability to select a folder\n- Support for Windows drive letters\n- Option to use the defaults as the selected value\n\n### 0.2.0\n\n- First public release\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python file chooser widget for use in Jupyter/IPython in conjunction with ipywidgets",
"version": "0.6.0",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "6c8ff0dad297a76f3a870148405370f2",
"sha256": "4555c24b30b819c91dc0ae5e6f7e4cf8f90e5cca531a9209a1fe4deee288d5c5"
},
"downloads": -1,
"filename": "ipyfilechooser-0.6.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6c8ff0dad297a76f3a870148405370f2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 11039,
"upload_time": "2021-09-15T22:31:55",
"upload_time_iso_8601": "2021-09-15T22:31:55.152850Z",
"url": "https://files.pythonhosted.org/packages/00/60/249e3444fcd9c833704741769981cd02fe2c7ce94126b1394e7a3b26e543/ipyfilechooser-0.6.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "740d0eb770a51fb9864e0f094fd33041",
"sha256": "41df9e4395a924f8e1b78e2804dbe5066dc3fdc233fb07fecfcdc2a0c9a7d8d3"
},
"downloads": -1,
"filename": "ipyfilechooser-0.6.0.tar.gz",
"has_sig": false,
"md5_digest": "740d0eb770a51fb9864e0f094fd33041",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 12737,
"upload_time": "2021-09-15T22:31:56",
"upload_time_iso_8601": "2021-09-15T22:31:56.261598Z",
"url": "https://files.pythonhosted.org/packages/13/63/a0bfdda0cdf002421632734e203e4692d72dc4e71cd006f101c90f9ba6d3/ipyfilechooser-0.6.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2021-09-15 22:31:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "crahan",
"github_project": "ipyfilechooser",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"lcname": "ipyfilechooser"
}
JSON
