Metadata-Version: 2.5
Name: dbf2stata
Version: 0.1.0
Summary: Convert DBF files to Stata .dta files with robust type and date handling.
Project-URL: Homepage, https://github.com/WilliamDormechele/dbf2stata
Project-URL: Repository, https://github.com/WilliamDormechele/dbf2stata
Project-URL: Issues, https://github.com/WilliamDormechele/dbf2stata/issues
Author: William Dormechele
License: MIT License
        
        Copyright (c) 2026 William Dormechele
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: data-conversion,dbase,dbf,dta,foxpro,stata
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.10
Requires-Dist: dbfread>=2.0.7
Requires-Dist: pandas>=2.2
Provides-Extra: test
Requires-Dist: pytest>=8; extra == 'test'
Description-Content-Type: text/markdown

# dbf2stata

`dbf2stata` converts every `.dbf` file in a folder to a Stata `.dta` file.
It is designed for research and legacy-data workflows where DBF files contain
mixed date, numeric, logical, character, memo, or FoxPro-style fields.

## Behaviour

- Converts all DBF files in one folder.
- Saves `.dta` files in the DBF folder by default.
- Lets the user choose a different output folder.
- Converts Stata variable names to lowercase by default.
- `--keep-case` retains the DBF field-name case.
- Converts DBF date fields to Stata daily dates and datetime fields to Stata datetimes.
- Handles Decimal, numeric, logical, character, memo, and binary-like fields.
- Reports per-file and overall conversion results.

## Install for Python users

When published to PyPI:

```bash
pip install dbf2stata
```

For isolated command-line installation, `pipx` is also suitable:

```bash
pipx install dbf2stata
```

For local development from this repository:

```bash
python -m pip install -e .
```

## Run interactively

```bash
dbf2stata
```

The program asks:

```text
Folder containing DBF files: C:\data\dbfs
Output folder [press Enter to use C:\data\dbfs]:
```

Press Enter at the second prompt to save the `.dta` files beside the DBFs.

## Run with command-line arguments

Save output beside the DBFs:

```bash
dbf2stata "C:\data\dbfs"
```

Use another output folder:

```bash
dbf2stata "C:\data\dbfs" --output "C:\data\stata"
```

Overwrite existing `.dta` files:

```bash
dbf2stata "C:\data\dbfs" --replace
```

Keep the field-name case stored in the DBF instead of lowercasing names:

```bash
dbf2stata "C:\data\dbfs" --keep-case
```

You can also run the package as a module:

```bash
python -m dbf2stata
```

## Stata command

The `stata/` directory contains:

- `dbf2stata.ado`
- `dbf2stata.sthlp`

The Stata command uses the same Python conversion engine, so Python and Stata
users receive the same type handling and output behaviour.

### Stata requirements

- Stata 16 or newer with Python configured.
- The `dbf2stata` Python package installed in the Python environment used by Stata.

Check Stata's Python configuration with:

```stata
python query
```

Once the ado package is installed, run:

```stata
dbf2stata
```

With no options, Stata asks you to select any DBF file in the folder. It then
converts every DBF in that folder and saves the `.dta` files in the same folder.

Specify the input folder directly:

```stata
dbf2stata, inputdir("C:\data\dbfs")
```

Specify another output folder:

```stata
dbf2stata, inputdir("C:\data\dbfs") outputdir("C:\data\stata")
```

Overwrite existing `.dta` files:

```stata
dbf2stata, inputdir("C:\data\dbfs") replace
```

Retain DBF field-name case:

```stata
dbf2stata, inputdir("C:\data\dbfs") keepcase
```

## Native Stata note

Stata itself includes `import dbase` for dBase III/IV DBF files. This project is
intended for batch conversion and for DBF collections that benefit from the
additional type handling provided by the Python conversion engine.

## Suggested repository layout

```text
dbf2stata/
├── pyproject.toml
├── README.md
├── LICENSE
├── src/
│   └── dbf2stata/
│       ├── __init__.py
│       ├── __main__.py
│       ├── cli.py
│       └── core.py
└── stata/
    ├── dbf2stata.ado
    └── dbf2stata.sthlp
```

## Testing

The conversion engine is covered by automated tests for:

- DBF discovery using `.dbf` and `.DBF` extensions
- lowercase variable names by default
- preservation of DBF field-name case with `--keep-case`
- numeric, logical and date conversion
- default same-folder output
- custom output directories
- overwrite protection
- explicit replacement of existing output files
- missing input-file handling

Run the test suite with:

```bash
python -m pytest
```

The initial development version was additionally validated on a legacy DBF collection containing 81 files and 382,566 records.

## Author

William Dormechele

## Citation

If you use `dbf2stata` in research, please cite the software using the citation metadata provided in `CITATION.cff`.

## License

MIT. See `LICENSE`.
