{"id":15442873,"url":"https://github.com/iamtugy/pyminio","last_synced_at":"2025-04-12T10:31:59.092Z","repository":{"id":62581745,"uuid":"298013628","full_name":"IamTugy/pyminio","owner":"IamTugy","description":"Pyminio is a python client wrapped like the os module to control minio server","archived":false,"fork":false,"pushed_at":"2024-08-20T21:18:51.000Z","size":69,"stargazers_count":40,"open_issues_count":5,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-10-18T13:16:35.938Z","etag":null,"topics":["aws-s3","minio","minio-client","object-storage","pyminio","python3"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/IamTugy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-09-23T15:27:28.000Z","updated_at":"2024-08-20T21:18:55.000Z","dependencies_parsed_at":"2024-08-21T05:31:20.229Z","dependency_job_id":null,"html_url":"https://github.com/IamTugy/pyminio","commit_stats":{"total_commits":31,"total_committers":7,"mean_commits":4.428571428571429,"dds":0.5806451612903225,"last_synced_commit":"12b52086d25690e1b96db36cde82a9ec0459b6cc"},"previous_names":["mmm1513/pyminio"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IamTugy%2Fpyminio","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IamTugy%2Fpyminio/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IamTugy%2Fpyminio/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IamTugy%2Fpyminio/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/IamTugy","download_url":"https://codeload.github.com/IamTugy/pyminio/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248553114,"owners_count":21123381,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws-s3","minio","minio-client","object-storage","pyminio","python3"],"created_at":"2024-10-01T19:31:02.529Z","updated_at":"2025-04-12T10:31:58.492Z","avatar_url":"https://github.com/IamTugy.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Pyminio\n[![PyPI](https://img.shields.io/pypi/v/pyminio?color=blue\u0026label=pypi%20version)]()\n[![PyPI](https://img.shields.io/pypi/pyversions/pyminio.svg?style=plastic)]()\n[![Downloads](https://pepy.tech/badge/pyminio)](https://pepy.tech/project/pyminio)\n#### Pyminio is a python client wrapped like the `os` module to control minio server.\n\nI have developed pyminio while trying to work with the minio's original python client with a lot of struggles. I had to read and understand minio's implementations to preform the most simple tasks.\n\nPyminio is a wrapper to [minio](https://github.com/minio/minio-py), that is more indecative for the user.\nIt works like `os` module, so you don't need to understand minio's concepts, and just using regular paths.\n\nThe latest Pyminio supports minio \u003e= 7.2\n\n## Content\n1. [Installation](#installation)\n2. [Setting up Pyminio](#setting-up-pyminio)\n3. [Usage](#usage)\n4. [Contribute](#contribute)\n\n## Installation\nUse the package manager [pip](https://pypi.org/project/pyminio/) to install pyminio.\n\n```bash\npip install pyminio\n```\n\n## Setting up Pyminio\n\nFirstly you need to set up your  [Minio Docker](https://hub.docker.com/r/minio/minio/), and acquire an ENDPOINT (URL), ACCESS_KEY, and a SECRET_KEY.\n\n- If you want to add your own minio object you can pass it in the constructor like so:\n\n    Install python's [Minio](https://docs.min.io/docs/python-client-quickstart-guide.html) module.\n\n    ```python\n    from minio import Minio\n    from pyminio import Pyminio\n\n    minio_obj = Minio(\n        endpoint='\u003cyour-minio-endpoint\u003e',  # e.g. \"localhost:9000/\"\n        access_key='\u003cyour-minio-access-key\u003e',\n        secret_key='\u003cyour-minio-secret-key\u003e'\n    )\n    pyminio_client = Pyminio(minio_obj=minio_obj)\n    ```\n\n- If you don't want to handle with minio, you can do this instead:\n\n    ```python\n    from pyminio import Pyminio\n\n    pyminio_client = Pyminio.from_credentials(\n        endpoint='\u003cyour-minio-endpoint\u003e',  # e.g. \"localhost:9000/\"\n        access_key='\u003cyour-minio-access-key\u003e',\n        secret_key='\u003cyour-minio-secret-key\u003e'\n    )\n    ```\n\n## Usage\n- [mkdirs](#mkdirsself-path-str)\n- [listdir](#listdirself-path-str-files_only-bool--false-dirs_only-bool--false---tuplestr)\n- [exists](#existsself-path-str---bool)\n- [isdir](#isdirself-path-str)\n- [truncate](#truncateself---pyminio)\n- [rmdir](#rmdirself-path-str-recursive-bool--false---pyminio)\n- [rm](#rmself-path-str-recursive-bool--false---pyminio)\n- [cp](#cpself-from_path-str-to_path-str-recursive-bool--false---pyminio)\n- [mv](#mvself-from_path-str-to_path-str-recursive-bool--false---pyminio)\n- [get](#getself-path-str---objectdata)\n- [get_last_object](#get_last_objectself-path-str---file)\n- [put_data](#put_dataself-path-str-data-bytes-metadata-dict--none)\n- [put_file](#put_fileself-file_path-str-to_path-str-metadata-dict--none)\n\n### \u003ca name=\"mkdirs\"\u003e\u003c/a\u003emkdirs(self, path: str)\n`Pyminio.mkdirs` will create the given full path if not exists like linux's `mkdir -p`.\n\nThis method must get a directory path or it will raise a ValueError.\n\n```python\n\u003e\u003e\u003e pyminio_client.mkdirs('/foo/bar/baz/')\n\u003e\u003e\u003e pyminio_client.mkdirs('/foo/bar/baz')\nValueError /foo/bar/baz is not a valid directory path. must be absolute and end with /\n```\n\n### \u003ca name=\"listdir\"\u003e\u003c/a\u003elistdir(self, path: str, files_only: bool = False, dirs_only: bool = False) -\u003e Tuple[str]\n`Pyminio.listdir` will return the directory's content as a tuple of directories and file names. Works like os's `listdir`.\n\nThis method must get a directory path or it will raise a ValueError.\n\n```python\n\u003e\u003e\u003e pyminio_client.listdir('/foo/bar/baz/')\n('file_name_1', 'file_name_2', 'directory_name/')\n```\n\nThere is an option to use the files_only flag to get only files and dirs_only to get only directories from listdir.\n\n```python\n\u003e\u003e\u003e pyminio_client.listdir('/foo/bar/baz/', files_only=True)\n('file_name_1', 'file_name_2')\n\u003e\u003e\u003e pyminio_client.listdir('/foo/bar/baz/', dirs_only=True)\n('directory_name/', )\n```\n\n### \u003ca name=\"exists\"\u003e\u003c/a\u003eexists(self, path: str) -\u003e bool\n`Pyminio.exists` will return a boolean that confirm rather this path exists or not in the server. Works like os's `path.exists`.\n\n```bash\n/\n├── foo\n│   └── bar\n│       └── baz\n│           ├── file_name_1\n│           └── file_name_2\n```\n\n```python\n\u003e\u003e\u003e pyminio_client.exists('/foo/bar/baz/file_name_1')\nTrue\n\u003e\u003e\u003e pyminio_client.exists('/foo/bar/baz/file_name_3')\nFalse\n\u003e\u003e\u003e pyminio_client.exists('/all/path/wrong/')  # not existing path\nFalse\n```\n\n### \u003ca name=\"isdir\"\u003e\u003c/a\u003eisdir(self, path: str)\n`Pyminio.isdir` will return True only if the given path exists and is a directory. Works like `os.path.isdir`.\n\n```python\n\u003e\u003e\u003e pyminio_client.isdir('/foo/bar/baz/file_name_1')  # existed file\nFalse\n\u003e\u003e\u003e pyminio_client.isdir('/foo/bar/baz/directory_name/')  # existed directory\nTrue\n\u003e\u003e\u003e pyminio_client.isdir('/all/path/wrong/but/directory/')  # not existed directory\nFalse\n```\n\n### \u003ca name=\"truncate\"\u003e\u003c/a\u003etruncate(self) -\u003e Pyminio\n`Pyminio.truncate` will delete all minio's content from the root directory.\n\n```python\n\u003e\u003e\u003e pyminio_client.truncate()\n```\n\n### \u003ca name=\"rmdir\"\u003e\u003c/a\u003ermdir(self, path: str, recursive: bool = False) -\u003e Pyminio\n`Pyminio.rmdir` will delete the specified directory. Works like linux's `rmdir` / `rm (-r)`.\n\nIt will raise a `DirectoryNotEmptyError` if given directory is not empty, except if the recursive flag is set and then it will delete given directory's path recursively.\n\nThis method must get a directory path or it will raise a ValueError.\n\n```python\n\u003e\u003e\u003e pyminio_client.rmdir('/foo/bar/baz/directory_name/')  # empty directory\n\u003e\u003e\u003e pyminio_client.rmdir('/foo/bar/')  # non-empty directory\nDirectoryNotEmptyError: can not recursively delete non-empty directory\n\u003e\u003e\u003e pyminio_client.rmdir('/foo/bar/', recursive=True)\n```\n\n### \u003ca name=\"rm\"\u003e\u003c/a\u003erm(self, path: str, recursive: bool = False) -\u003e Pyminio\n`Pyminio.rm` works like [rmdir](#rmdirself-path-str-recursive-bool--false---pyminio) only that it can delete files too. Works like linux's `rm (-r)`.\n\n```python\n\u003e\u003e\u003e pyminio_client.rm('/foo/bar/baz/file_name')\n```\n\n### \u003ca name=\"cp\"\u003e\u003c/a\u003ecp(self, from_path: str, to_path: str, recursive: bool = False) -\u003e Pyminio\n`Pyminio.cp` will copy one file or directory to given destination. Works like linux's `cp (-r)`.\n\nThis method can only copy recursively when the recursive flag is True. If not, it will raise a ValueError.\n\n### How will the copy accure? (all directories are copied recursively in this examples)\n| src path   | dst path  | dst exists | new dst      | Explain                                                                |\n| ---------- | --------- | ---------- | ------------ | ---------------------------------------------------------------------- |\n| /foo/bar   | /foo/baz  |    ---     | /foo/baz     | The file's name will be copied from bar to baz as well.                |\n| /foo1/bar  | /foo2/    |    True    | /foo/bar     | The file will be copied to '/foo2/bar'                                 |\n| /foo/bar/  | /foo/     |    True    | /foo/        | The content of '/foo/bar/' will be copied to '/foo/'                   |\n| /foo1/bar/ | /foo2/    |   False    | /foo2/bar/   | '/foo1/bar/' will be copied recursively to '/foo2/bar/'                |\n| /foo1/bar/ | /foo2/baz |    ---     |     ---      | ValueError will be raised in attempting to copy directory in to a file |\n\n```python\n\u003e\u003e\u003e pyminio_client.cp('/foo/bar', '/foo/baz')\n\u003e\u003e\u003e pyminio_client.cp('/foo1/bar', '/foo2/')\n\u003e\u003e\u003e pyminio_client.cp('/foo/bar/', '/foo/', recursive=True)\n\u003e\u003e\u003e pyminio_client.cp('/foo1/bar/', '/foo2/', recursive=True)\n\u003e\u003e\u003e pyminio_client.cp('/foo1/bar/', '/foo2/baz', recursive=True)\nValueError: can not activate this method from directory to a file.\n```\n\n### \u003ca name=\"mv\"\u003e\u003c/a\u003emv(self, from_path: str, to_path: str, recursive: bool = False) -\u003e Pyminio\n`Pyminio.mv` works like [cp](#cpself-from_path-str-to_path-str-recursive-bool--false---pyminio) only that it removes the source after the transfer has been completed. Works like linux's `mv`.\n\nThis method can only move recursively when the recursive flag is True. If not, it will raise a ValueError.\n\n```python\n\u003e\u003e\u003e pyminio_client.mv('/foo/bar/', '/foo/baz/')\n```\n\n### \u003ca name=\"get\"\u003e\u003c/a\u003eget(self, path: str) -\u003e ObjectData\n`Pyminio.get` return an object from given path. This object will be returned as a `pyminio.File` object or an `pyminio.Folder` object, that both inherit from `pyminio.ObjectData`.\n\nThis objects will contain metadata, their path and name.\n\n```python\n\u003e\u003e\u003e pyminio_client.get('/foo/bar/baz')\nFile(name='baz', \n     full_path='/foo/bar/baz', \n     metadata={\n         'is_dir': False, \n         'last_modified': time.struct_time(...), \n         'size': ..., \n         'content-type': ...\n     }, \n     data=...)\n```\n\n### \u003ca name=\"get_last_object\"\u003e\u003c/a\u003eget_last_object(self, path: str) -\u003e File\n`Pyminio.get_last_object` will return the last modified object inside a given directory.\n\nThis method must get a directory path or it will raise a ValueError.\n\n```python\n\u003e\u003e\u003e pyminio_client.get_last_object('/foo/bar/')\nFile(name='baz', \n     full_path='/foo/bar/baz', \n     metadata={\n         'is_dir': False, \n         'last_modified': time.struct_time(...), \n         'size': ..., \n         'content-type': ...\n     }, \n     data=...)\n```\n\n### \u003ca name=\"put_data\"\u003e\u003c/a\u003eput_data(self, path: str, data: bytes, metadata: Dict = None)\n`Pyminio.put_data` gets a path, data in bytes, and some metadata, and create an object inside the given path.\n\n```python\n\u003e\u003e\u003e data = b'test'\n\u003e\u003e\u003e metadata = {'Pyminio-is': 'Awesome'}\n\u003e\u003e\u003e pyminio_client.put_data(path='/foo/bar/baz', data=data, metadata=metadata)\n```\n\n### \u003ca name=\"put_file\"\u003e\u003c/a\u003eput_file(self, file_path: str, to_path: str, metadata: Dict = None)\n`Pyminio.put_file` works like [put_data](#put_dataself-path-str-data-bytes-metadata-dict--none) only that instead of data it gets a path to a file in you computer. Then it will copy this file to the given location.\n\n```python\n\u003e\u003e\u003e metadata = {'Pyminio-is': 'Awesome'}\n\u003e\u003e\u003e pyminio_client.put_file(to_path='/foo/bar/baz', file_path='/mnt/some_file', metadata=metadata)\n```\n\n## Contribute\n\nAll contributions are welcome:\n\n- Read the [issues](https://github.com/IamTugy/pyminio/issues), Fork the [project](https://github.com/IamTugy/pyminio) and create a new Pull Request.\n- Request a new feature creating a `New issue` with the `enhancement` tag.\n- Find any kind of errors in the code and create a `New issue` with the details, or fork the project and do a Pull Request.\n- Suggest a better or more pythonic way for existing examples.\n\n### Work environment\n\nAfter forking the project, make sure you have poetry installed, \nthan install the dependencies using\n```bash\npoetry install\n```\n\nAlso install pre-commit and activate it:\n```bash\npip install pre-commit\npre-commit install\n```\n\ndownload the [minio docker](https://hub.docker.com/r/minio/minio/) and start an instance in your computer for development and testing.\n\nExport The same environment variables you've used to set up your local minio:\n```bash\nexport MINIO_TEST_CONNECTION=\"\u003cyour API host\u003e\" # example: 127.0.0.1:9000\nexport MINIO_TEST_ACCESS_KEY=\"\u003cyour user\u003e\" # example: ROOTNAME\nexport MINIO_TEST_SECRET_KEY=\"\u003cyour password\u003e\" # example: CHANGEME123\n```\n\nto run the tests run:\n```bash\npoetry run pytest tests\n```\n#### Don't forget to write tests, and to run all the tests before making a pull request.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiamtugy%2Fpyminio","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiamtugy%2Fpyminio","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiamtugy%2Fpyminio/lists"}