{"id":37654871,"url":"https://github.com/tech4242/csv2vcard","last_synced_at":"2026-01-16T11:39:58.267Z","repository":{"id":31855653,"uuid":"111790767","full_name":"tech4242/csv2vcard","owner":"tech4242","description":"📠 A pip package that parses a .csv file of contacts and automatically creates vCards","archived":false,"fork":false,"pushed_at":"2026-01-14T15:02:25.000Z","size":93,"stargazers_count":9,"open_issues_count":2,"forks_count":10,"subscribers_count":2,"default_branch":"master","last_synced_at":"2026-01-14T17:35:29.836Z","etag":null,"topics":[],"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/tech4242.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2017-11-23T09:39:55.000Z","updated_at":"2026-01-14T13:52:40.000Z","dependencies_parsed_at":"2022-08-26T19:52:27.681Z","dependency_job_id":null,"html_url":"https://github.com/tech4242/csv2vcard","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/tech4242/csv2vcard","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tech4242%2Fcsv2vcard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tech4242%2Fcsv2vcard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tech4242%2Fcsv2vcard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tech4242%2Fcsv2vcard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tech4242","download_url":"https://codeload.github.com/tech4242/csv2vcard/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tech4242%2Fcsv2vcard/sbom","scorecard":{"id":871829,"data":{"date":"2025-08-11","repo":{"name":"github.com/tech4242/csv2vcard","commit":"8893fe455a2dfd2066ddc1dc4cf445e15f023d9f"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":3.5,"checks":[{"name":"Code-Review","score":0,"reason":"Found 0/30 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Dangerous-Workflow","score":-1,"reason":"no workflows found","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"SAST","score":0,"reason":"no SAST tool detected","details":["Warn: no pull requests merged into dev branch"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Pinned-Dependencies","score":-1,"reason":"no dependencies found","details":null,"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Token-Permissions","score":-1,"reason":"No tokens found","details":null,"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE.txt:0","Info: FSF or OSI recognized license: MIT License: LICENSE.txt:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Branch-Protection","score":-1,"reason":"internal error: error during branchesHandler.setup: internal error: githubv4.Query: Resource not accessible by integration","details":null,"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}}]},"last_synced_at":"2025-08-24T04:29:40.048Z","repository_id":31855653,"created_at":"2025-08-24T04:29:40.048Z","updated_at":"2025-08-24T04:29:40.048Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28478353,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T06:30:42.265Z","status":"ssl_error","status_checked_at":"2026-01-16T06:30:16.248Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":[],"created_at":"2026-01-16T11:39:58.193Z","updated_at":"2026-01-16T11:39:58.258Z","avatar_url":"https://github.com/tech4242.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# csv2vcard\n\n[![Downloads](https://static.pepy.tech/badge/csv2vcard)](https://pepy.tech/projects/csv2vcard)\n[![PyPI](https://img.shields.io/pypi/v/csv2vcard.svg)](https://pypi.org/project/csv2vcard/)\n[![codecov](https://codecov.io/gh/tech4242/csv2vcard/graph/badge.svg?token=VUG1OXUH45)](https://codecov.io/gh/tech4242/csv2vcard)\n[![Python](https://img.shields.io/pypi/pyversions/csv2vcard.svg)](https://pypi.org/project/csv2vcard/)\n[![Typed](https://img.shields.io/badge/typed-py.typed-blue.svg)](https://peps.python.org/pep-0561/)\n[![Typer](https://img.shields.io/badge/CLI-Typer-2bbc8a.svg)](https://typer.tiangolo.com/)\n[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n[![License](https://img.shields.io/pypi/l/csv2vcard.svg)](https://github.com/tech4242/csv2vcard/blob/master/LICENSE.txt)\n\n\u003c/div\u003e\n\nA Python library for converting CSV files to vCard format (3.0 and 4.0).\n\nCreate vCards from a spreadsheet of contacts - useful for business cards, QR codes, CRM imports, or transferring contacts between systems.\n\n## Features\n\n- **vCard 3.0 and 4.0 support** - Generate either format\n- **Custom CSV mapping** - Map any CSV column names to vCard fields\n- **Batch processing** - Convert entire directories of CSV files\n- **Single-file output** - Combine all contacts into one .vcf file\n- **Auto-detect encoding** - Handles various file encodings\n- **Command-line interface** - Convert files directly from terminal\n- **Library API** - Use programmatically in your Python code\n- **Type hints** - Full typing support for IDE autocomplete\n- **Security** - Input validation and path traversal protection\n- **Zero dependencies** - Core library uses only Python stdlib\n\n## Installation\n\n```bash\n# Basic installation (library only)\npip install csv2vcard\n\n# With CLI support\npip install csv2vcard[cli]\n\n# With encoding detection\npip install csv2vcard[encoding]\n\n# Full installation\npip install csv2vcard[all]\n```\n\n## Quick Start\n\n### Command Line\n\n```bash\n# Convert a CSV file to vCards\ncsv2vcard convert contacts.csv\n\n# Specify output directory and vCard version\ncsv2vcard convert contacts.csv -o ./vcards -V 4.0\n\n# Convert all CSVs in a directory\ncsv2vcard convert ./csv_folder/\n\n# Export all contacts to a single file\ncsv2vcard convert contacts.csv --single-vcard\n\n# Use custom column mapping\ncsv2vcard convert data.csv -m mapping.json\n\n# Show example mapping file\ncsv2vcard mapping\n\n# Create a test vCard (Forrest Gump)\ncsv2vcard test\n```\n\n### Python Library\n\n```python\nfrom csv2vcard import csv2vcard, test_csv2vcard\n\n# Basic usage - creates vCards in ./export/\ncsv2vcard(\"contacts.csv\", \",\")\n\n# With options\nfrom csv2vcard.models import VCardVersion\n\ncsv2vcard(\n    \"contacts.csv\",\n    \",\",\n    output_dir=\"./vcards\",\n    version=VCardVersion.V4_0,\n    single_file=True,  # All contacts in one file\n    mapping_file=\"mapping.json\",  # Custom column names\n)\n\n# Convert entire directory\ncsv2vcard(\"./csv_folder/\", \",\", output_dir=\"./vcards\")\n\n# Test with sample contact\ntest_csv2vcard()\n```\n\n## CSV Format\n\nYour CSV file should have column headers that match vCard fields. Use the default names or create a custom mapping.\n\n### Default Column Names\n\n```\nlast_name,first_name,middle_name,name_prefix,name_suffix,nickname,gender,birthday,anniversary,phone,email,website,org,title,role,street,city,region,p_code,country,note\n```\n\n**Required:** `last_name`, `first_name`\n\n**Optional:** All other fields\n\n### Example CSV\n\n```csv\nlast_name,first_name,title,org,phone,email,street,city,p_code,country,birthday,note\nGump,Forrest,Shrimp Man,Bubba Gump Shrimp Co.,+1234567890,forrest@example.com,42 Plantation St.,Baytown,30314,USA,1944-06-06,Life is like a box of chocolates\nDoe,Jane,Developer,Tech Corp,+0987654321,jane@example.com,123 Main St.,New York,10001,USA,,\n```\n\n### Custom Column Mapping\n\nCreate a JSON file to map your CSV column names to vCard fields:\n\n```json\n{\n  \"first_name\": [\"Given Name\", \"FirstName\", \"First\"],\n  \"last_name\": [\"Surname\", \"FamilyName\", \"Last\"],\n  \"email\": [\"Email Address\", \"E-Mail\"],\n  \"phone\": [\"Phone Number\", \"Mobile\", \"Tel\"]\n}\n```\n\nThen use it:\n```bash\ncsv2vcard convert data.csv -m mapping.json\n```\n\n## CLI Reference\n\n```\ncsv2vcard convert [OPTIONS] SOURCE\n\nArguments:\n  SOURCE  Path to CSV file or directory containing CSV files\n\nOptions:\n  -d, --delimiter TEXT      CSV field delimiter (default: \",\")\n  -o, --output PATH         Output directory (default: ./export/)\n  -V, --vcard-version TEXT  vCard version: 3.0 or 4.0 (default: 3.0)\n  -1, --single-vcard        Export all contacts to a single .vcf file\n  -m, --mapping PATH        Path to JSON mapping file\n  -e, --encoding TEXT       CSV file encoding (auto-detected if not set)\n  --strict                  Exit on validation errors\n  -v, --verbose             Enable verbose output\n  --version                 Show version and exit\n  --help                    Show help message\n```\n\n## API Reference\n\n### Main Functions\n\n```python\nfrom csv2vcard import csv2vcard, test_csv2vcard\nfrom csv2vcard.models import VCardVersion\n\n# Convert CSV to vCards\nfiles = csv2vcard(\n    csv_filename,           # Path to CSV file or directory\n    csv_delimiter=\",\",      # Field delimiter\n    output_dir=None,        # Output directory (default: ./export/)\n    version=VCardVersion.V3_0,  # vCard version\n    strict=False,           # Raise on validation errors\n    single_file=False,      # Combine all contacts into one file\n    encoding=None,          # File encoding (auto-detected)\n    mapping_file=None,      # Path to JSON mapping file\n)\n# Returns: List[Path] of created vCard files\n\n# Test with sample contact\ntest_csv2vcard(\n    output_dir=None,\n    version=VCardVersion.V3_0,\n)\n```\n\n### Models\n\n```python\nfrom csv2vcard.models import Contact, VCardVersion, VCardOutput\n\n# Create a contact programmatically\ncontact = Contact(\n    last_name=\"Doe\",\n    first_name=\"John\",\n    middle_name=\"William\",\n    email=\"john@example.com\",\n    phone=\"+1234567890\",\n    birthday=\"1990-01-15\",\n    nickname=\"Johnny\",\n)\n\n# Or from a dictionary\ncontact = Contact.from_dict({\"last_name\": \"Doe\", \"first_name\": \"John\"})\n\n# vCard versions\nVCardVersion.V3_0  # vCard 3.0 (RFC 2426)\nVCardVersion.V4_0  # vCard 4.0 (RFC 6350)\n```\n\n## Supported vCard Fields\n\n| Field | Description | Example |\n|-------|-------------|---------|\n| `last_name` | Family name | Doe |\n| `first_name` | Given name | John |\n| `middle_name` | Middle name | William |\n| `name_prefix` | Honorific prefix | Dr. |\n| `name_suffix` | Honorific suffix | Jr. |\n| `nickname` | Nickname | Johnny |\n| `gender` | Gender (M/F/O/N/U) | M |\n| `birthday` | Birth date (YYYY-MM-DD) | 1990-01-15 |\n| `anniversary` | Anniversary date | 2015-06-20 |\n| `phone` | Phone number | +1234567890 |\n| `email` | Email address | john@example.com |\n| `website` | Website URL | https://example.com |\n| `org` | Organization | Acme Corp |\n| `title` | Job title | Developer |\n| `role` | Role/function | Team Lead |\n| `street` | Street address | 123 Main St |\n| `city` | City | New York |\n| `region` | State/province | NY |\n| `p_code` | Postal code | 10001 |\n| `country` | Country | USA |\n| `note` | Notes | Any additional info |\n\n## Requirements\n\n- Python 3.9 or higher\n- For CLI: `typer` (installed with `csv2vcard[cli]`)\n- For encoding detection: `charset-normalizer` (installed with `csv2vcard[encoding]`)\n\n## Development\n\n```bash\n# Clone the repository\ngit clone https://github.com/tech4242/csv2vcard.git\ncd csv2vcard\n\n# Install dev dependencies\npip install -e .[dev]\n\n# Run tests\npytest\n\n# Run tests with coverage\npytest --cov=csv2vcard --cov-report=term-missing\n\n# Type checking\nmypy csv2vcard\n\n# Linting\nruff check csv2vcard\n```\n\n## License\n\nMIT License - see [LICENSE.txt](LICENSE.txt)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftech4242%2Fcsv2vcard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftech4242%2Fcsv2vcard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftech4242%2Fcsv2vcard/lists"}