{"id":26949660,"url":"https://github.com/numerous-com/numerous-files","last_synced_at":"2025-10-12T03:16:29.318Z","repository":{"id":237938026,"uuid":"792738396","full_name":"numerous-com/numerous-files","owner":"numerous-com","description":"Numerous Files simplifies file storage interfaces for web applications across different environments. This package allows seamless swapping between cloud, local, and in-memory storage without code modifications, facilitated through environment variables. Ideal for developers aiming for consistency across development, testing, and production phases.","archived":false,"fork":false,"pushed_at":"2024-10-17T17:18:56.000Z","size":60,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-23T10:29:38.335Z","etag":null,"topics":["aws-s3","cloud-storage","environment-variables","file-storage","in-memory-filesystem","in-memory-storage","local-storage","web-development"],"latest_commit_sha":null,"homepage":"https://www.numerous.com","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/numerous-com.png","metadata":{"files":{"readme":"docs/README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","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":"2024-04-27T12:42:07.000Z","updated_at":"2024-10-17T17:18:59.000Z","dependencies_parsed_at":"2024-10-20T14:03:19.074Z","dependency_job_id":null,"html_url":"https://github.com/numerous-com/numerous-files","commit_stats":null,"previous_names":["numerous-com/numerous-files"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/numerous-com%2Fnumerous-files","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/numerous-com%2Fnumerous-files/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/numerous-com%2Fnumerous-files/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/numerous-com%2Fnumerous-files/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/numerous-com","download_url":"https://codeload.github.com/numerous-com/numerous-files/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246899655,"owners_count":20851899,"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","cloud-storage","environment-variables","file-storage","in-memory-filesystem","in-memory-storage","local-storage","web-development"],"created_at":"2025-04-02T22:17:02.089Z","updated_at":"2025-10-12T03:16:24.285Z","avatar_url":"https://github.com/numerous-com.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Welcome to Numerous Files\n\nThe purpose of this package is to make a simple way to interface with both cloud, local, and in-memory file storage to support a development and production workflow for web applications needing file storage. The idea is to have a common inteface where the backend can be changed without making code changes by setting env variables. In this way local development and testing can use in-memory or local file storage, eventually run tests with a cloud file storage provider and use cloud file storage in production.\n\nSimply use the factory method to get a file manager instance. You can control which file manager will be used by setting the env variable `NUMEROUS_FILES_BACKEND` to either `IN-MEMORY` to use the memory based file system, `LOCAL` to use a local folder, or `AWS_S3` to use an S3 bucket on AWS.\n\n## Installation\n\nInstall the package using pip:\n\n```bash\npip install numerous-files\n```\n\n## Usage\n\nUse `file_manager_factory` to get a file manager configured based on the current environment.\n\n```python\nfrom numerous.files import file_manager_factory\n\nfile_manager = file_manager_factory()\n```\n\nUse `file_manager_factory` to upload and download files.\n```python\n# put a local file to file manager\nfile_manager.put(\"my_local_file.txt\", \"folder/and_name_on_file_backend.txt\")\n\n# get the file just put\nfile_manager.get(\"folder/and_name_on_file_backend.txt\", \"name_i_want_the_file_to_have_locally\")\n\n# open a file\nwith file_manager.open(\"folder/and_name_on_file_backend.txt\", \"r\") as file:\n    content = file.read()\n```\n\nTo list, copy, move and remove files.\n```python\n# list files in the file_managers backend\nfile_manager.list()\n\n# Optionally add a subfolder to list files from\nfile_manger.list(\"my_folder\")\n\n# Remove a file\nfile_manager.remove(\"my_file.txt\")\n\n# Copy a file\nfile_manager.copy(\"from/my_file.txt\",\"to/my_copy.txt\")\n\n# Move a file\nfile_manager.copy(\"from/my_file.txt\",\"to/my_copy.txt\")\n```\n\n## AWS Backend\n\nYou can use the AWS backend if you have an AWS account. \n\nTo save files on AWS S3 a bucket (need to be created before using `file_manager`) and a base prefix is needed to be specified using the env variables `NUMEROUS_FILES_BUCKET` and `NUMEROUS_FILES_BASE_PREFIX`.\n\nIn order for the file_manager to access your files on aws, you need to provide authentication to access AWS.\n\n### AWS authentication\n\nIf you set the env variables `NUMEROUS_FILES_AWS_ACCESS_KEY` and `NUMEROUS_FILES_AWS_SECRET_KEY` with your aws credentials they will be used to authenticate. In case these env variables are not set the client will authenticate with the AWS credentials from your environment.\n\nIf needed you can supply the names of the env variables you use to store information of the bucket, base_prefix, aws_access and aws_secrets to the file_manager_factory method as the following key word arguments: bucket, base_prefix, aws_access_key_id, and aws_secret_access_key.\n\n## In Memory Backend\n\nThe in-memory backend does not need any configuration. Please be aware, files stored in the in-memory backend will not be persisted.\n\n## Local Backend\n\nFor the local backend you can configure the base folder for the file manager from where all paths will be relative. You set the workfolder by using the `workfolder` keyword when using the factory method.\n\n# Documentation\nFor a more complete documentation of `numerous-files` please visit [numerous-files-docs](https://numerous-files.readthedocs.io/en/latest/) on readthedocs.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnumerous-com%2Fnumerous-files","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnumerous-com%2Fnumerous-files","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnumerous-com%2Fnumerous-files/lists"}