Metadata-Version: 2.4
Name: vnstock-installer
Version: 3.1.3
Summary: Professional GUI installer for Vnstock packages
Author-email: Vnstock Team <support@vnstocks.com>
License: Proprietary
Project-URL: Homepage, https://github.com/vnstock/vnstock-installer
Project-URL: Documentation, https://vnstocks.com/docs
Project-URL: Repository, https://github.com/vnstock/vnstock-installer
Project-URL: Bug Tracker, https://github.com/vnstock/vnstock-installer/issues
Keywords: vnstock,installer,gui,vietnam,stock,market
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Eel>=0.11.0
Requires-Dist: requests>=2.31.0
Requires-Dist: vnai>=2.6.2
Requires-Dist: uv
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: license-file

# Vnstock Installer

<div align="center">

![Vnstock Logo](https://vnstocks.com/_next/image?url=%2Fimg%2Fvnstock-logo-rec-rgb.png&w=256&q=75)

**Professional GUI Installer for Vnstock Packages**

[![Python Version](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Status](https://img.shields.io/badge/status-beta-yellow.svg)]()

</div>

## 📖 Overview

Vnstock Installer là công cụ cài đặt GUI chuyên nghiệp cho các gói thư viện Vnstock Sponsored. Được xây dựng với kiến trúc web-based hiện đại sử dụng Eel framework, mang đến trải nghiệm người dùng mượt mà và giao diện đẹp mắt.

## ✨ Features

- **🎨 Modern Web UI**: Giao diện web responsive, đẹp mắt với Eel
- **🐍 Python Version Detection**: Tự động phát hiện Python >= 3.10
- **📦 Virtual Environment Support**: Hỗ trợ tạo và quản lý venv
- **🔐 API Authentication**: Xác thực API key an toàn
- **📊 Package Management**: Quản lý và cài đặt nhiều packages
- **📝 Real-time Logging**: Theo dõi quá trình cài đặt real-time
- **🌐 Multi-language**: Hỗ trợ Tiếng Việt và English
- **💻 Cross-platform**: Windows, macOS, Linux

## 🚀 Quick Start

### Installation

```bash
# Cài đặt từ chỉ mục riêng của Vnstock (PyPI đang cách ly vnai/vnstock,
# còn tên vnstock-installer trên PyPI đã bị người khác chiếm với bản 99.0.0,
# nên luôn ghim đúng phiên bản khi dùng pip)
pip install --extra-index-url https://vnstocks.com/api/simple "vnstock-installer==3.1.3"

# Hoặc cài đặt từ source
git clone https://github.com/vnstock/vnstock-installer.git
cd vnstock-installer
pip install --extra-index-url https://vnstocks.com/api/simple -e .
```

### Usage

```bash
# Chạy installer
vnstock-installer

# Với options
vnstock-installer --language vi
vnstock-installer --default-browser
vnstock-installer --logging-level DEBUG
```

### Command-line Options

```
-db, --default-browser    Sử dụng trình duyệt mặc định thay vì Chrome/Edge
-nu, --no-ui              Chỉ khởi động server (không mở browser)
-c, --config FILE         Load cấu hình từ JSON file
-lang, --language CODE    Ngôn ngữ mặc định (vi/en)
--logging-level LEVEL     Mức độ logging (DEBUG/INFO/WARNING/ERROR/CRITICAL)
--base-url URL            Vnstock API base URL
-v, --version             Hiển thị version
```

### Chế độ dòng lệnh (CLI) — cho AI agent, SSH, Windows

Chạy cùng luồng với giao diện web (đăng ký thiết bị → cài gói phụ thuộc → cài gói tài trợ) nhưng không mở trình duyệt. Bản CLI dạng shell (`vnstock_installer_cli`) chỉ chạy trên macOS/Linux; chế độ này chạy được trên mọi hệ điều hành, kể cả Windows.

Cú pháp giống bản `.run` của macOS/Linux, chỉ khác cách gọi:

| Hệ điều hành | Lệnh |
| --- | --- |
| macOS / Linux | `bash vnstock-cli-installer.run -- --non-interactive` |
| Windows (và mọi OS đã cài gói này) | `vnstock-cli-installer --non-interactive` |
| Khi `vnstock-cli-installer` không có trong PATH | `python -m vnstock_installer --non-interactive` |

```powershell
# Khoá lấy từ ~/.vnstock/api_key.json hoặc biến VNSTOCK_API_KEY — không gõ khoá trên dòng lệnh
vnstock-cli-installer                      # tương tác: hỏi khoá nếu chưa lưu
vnstock-cli-installer --non-interactive    # không hỏi gì, cài mọi gói tier cho phép
vnstock-cli-installer --non-interactive --venv-path "D:\envs\.venv" --language en

# Tuỳ chọn thêm (chỉ có ở trình cài Python)
vnstock-cli-installer --list-packages
vnstock-cli-installer --non-interactive --packages vnstock_data,vnstock_ta --json
```

Chạy `vnstock-installer` hoặc `python -m vnstock_installer` không kèm tuỳ chọn thì vẫn mở giao diện như cũ; bất kỳ tuỳ chọn nào dưới đây đều chuyển sang chế độ dòng lệnh.

```
--cli, --headless     Chế độ dòng lệnh khi không kèm tuỳ chọn nào khác (hỏi khoá)
--api-key KEY         API key (mặc định: biến VNSTOCK_API_KEY, rồi ~/.vnstock/api_key.json)
--packages LIST       Danh sách gói, phân cách bằng dấu phẩy, hoặc 'all' (mặc định: all)
--list-packages       In các gói API key được phép cài rồi thoát
--python PATH         Python dùng để tạo venv (mặc định: Python đang chạy installer)
--venv-path PATH      Đường dẫn venv (mặc định: VNSTOCK_VENV_PATH hoặc ~/.venv)
--no-venv             Cài thẳng vào --python, không dùng venv
--non-interactive     Không hỏi gì (tự bật khi stdin không phải terminal)
--json                In kết quả thành một object JSON trên stdout
--verbose             In log chi tiết ra stderr
```

Tiến trình in ra stderr, stdout chỉ chứa kết quả. Mã thoát: `0` cài đủ, `1` lỗi môi trường/xác thực/gói phụ thuộc hoặc tài khoản Community, `2` sai tham số hoặc gói vượt quyền của tier, `3` một số gói tài trợ lỗi hoặc bị bỏ qua.

### Gói theo tier

| Tier | Gói tài trợ được cài |
| --- | --- |
| Community (miễn phí) | không có — cài `vnstock` bằng pip |
| Bronze | `vnstock_data` |
| Silver | `vnstock_data`, `vnstock_ta`, `vnstock_news` |
| Golden, Diamond | thêm `vnstock_pipeline` (cần Python 3.11+) |

Server lọc gói theo tier (`/api/vnstock/packages/list`); installer hiện gói bị khoá kèm tier cần nâng cấp, và chỉ in lệnh kiểm tra `import ...` cho các gói đã cài thật. Bảng đối chiếu nằm ở `vnstock_installer/tiers.py`, sao từ `src/config/vnstock-packages.ts` của web.

## 🏗️ Architecture

Vnstock Installer được thiết kế theo kiến trúc module hóa tương tự auto-py-to-exe:

```
vnstock_installer/
├── __init__.py          # Package initialization
├── __main__.py          # Entry point & argument parsing
├── config.py            # Configuration management
├── ui.py                # Eel-based UI backend
├── cli.py               # Terminal mode (vnstock-cli-installer), same flow without Eel
├── tiers.py             # Sponsor tier → packages, verify commands
├── api.py               # Vnstock API client
├── installer.py         # Installation logic
├── validation.py        # Input validators
├── utils.py             # Utility functions
└── web/                 # Frontend assets
    ├── index.html       # Main UI
    ├── css/
    │   ├── main.css     # Main styles
    │   └── tabs.css     # Tab styles
    └── js/
        ├── main.js      # Core JavaScript
        ├── tabs.js      # Tab switching
        └── install.js   # Installation logic
```

### Key Components

#### Backend (Python)

- **`api.py`**: `VnstockAPIClient` - Xử lý authentication, package listing, downloads
- **`installer.py`**: `VnstockInstaller` - Quản lý quá trình cài đặt packages
- **`ui.py`**: Eel-based backend với `@eel.expose` functions
- **`config.py`**: Centralized configuration management

#### Frontend (Web)

- **HTML/CSS**: Modern, responsive UI với Vnstock branding
- **JavaScript**: Asynchronous communication với Python backend qua Eel
- **Progressive Enhancement**: Graceful degradation cho browsers cũ

## 🎨 UI Design

- **Colors**: Green (#4CAF50) primary, Purple (#8C52FF) accent
- **Typography**: System fonts với fallbacks
- **Responsive**: Mobile-first approach
- **Accessibility**: ARIA labels, keyboard navigation

## 📦 Development

### Setup Development Environment

```bash
# Clone repository
git clone https://github.com/vnstock/vnstock-installer.git
cd vnstock-installer

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install development dependencies
pip install -e ".[dev]"

# Install pre-commit hooks (optional)
pip install pre-commit
pre-commit install
```

### Project Structure

```
vnstock_installer/
├── vnstock_installer/    # Source code
├── tests/                # Unit tests
├── docs/                 # Documentation
├── setup.py              # Setup script
├── pyproject.toml        # Modern Python packaging
├── requirements.txt      # Dependencies
├── README.md             # This file
└── LICENSE               # MIT License
```

### Running Tests

```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=vnstock_installer

# Run specific test
pytest tests/test_api.py
```

### Code Quality

```bash
# Format code
black vnstock_installer/

# Lint code
ruff check vnstock_installer/

# Type checking
mypy vnstock_installer/
```

### CI: chế độ dòng lệnh trên Windows / macOS / Linux

Workflow [`.github/workflows/cli-test.yml`](.github/workflows/cli-test.yml):

- **Mỗi lần push / PR** (không cần khoá, không tốn thiết bị): build bản obfuscate bằng `obfuscate/obfuscate_script.py --yes --version keep`, rồi trên 3 hệ điều hành × Python 3.10 và 3.13 chạy [`tests/ci/cli_smoke.py`](tests/ci/cli_smoke.py) (hai cách gọi, mã thoát, JSON, tiếng Việt qua pipe, GUI khởi động), gọi thử từ PowerShell / cmd / bash, và [`tests/ci/mock_install.py`](tests/ci/mock_install.py) (cài thật vnai + vnstock + gói phụ thuộc vào venv, API giả lập, `uv` bị ẩn khỏi PATH).
- **Chạy tay** (Actions → *Run workflow* → tick `real_install`): cài thật `vnstock-cli-installer --non-interactive --json` bằng secret `VNSTOCK_API_KEY`, kiểm tra bằng [`tests/ci/check_e2e.py`](tests/ci/check_e2e.py). Mỗi lần chạy **đăng ký 1 thiết bị trên mỗi hệ điều hành** (runner là máy mới), nên dùng tài khoản riêng cho CI và gỡ thiết bị cũ tại <https://vnstocks.com/account?section=devices>.

## 🤝 Contributing

Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- Inspired by [auto-py-to-exe](https://github.com/brentvollebregt/auto-py-to-exe)
- Built with [Eel](https://github.com/ChrisKnott/Eel)
- Vnstock Team for the amazing financial data library

## 📞 Support

- 📧 Email: support@vnstocks.com
- 🌐 Website: https://vnstocks.com
- 📖 Documentation: https://vnstocks.com/docs
- 🐛 Issues: https://github.com/vnstock/vnstock-installer/issues

## 🗺️ Roadmap

- [ ] OAuth2 browser authentication
- [ ] Package update notifications
- [ ] Installation rollback capability
- [ ] Custom Python interpreter selection
- [ ] Dark theme support
- [ ] Internationalization (more languages)
- [ ] Auto-update mechanism

---

<div align="center">
Made with ❤️ by Vnstock Team
</div>
