# twstock for Taiwan Stock Data and Market Signals

> twstock is a Python package for retrieving Taiwan stock prices, securities metadata, realtime quotes, and technical-analysis results from TWSE and TPEX sources. It suits Python developers who need a compact Taiwan-market client, subject to upstream request limits and source-dependent collection.

**mlouielu/twstock** — 台灣股市股票價格擷取 (含即時股票資訊) - Taiwan Stock Opendata with realtime

- Repository: https://github.com/mlouielu/twstock
- Website: http://twstock.readthedocs.io/
- Stars: 1,528 · Forks: 410
- Language: Python
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/mlouielu-twstock

## What twstock Collects for Taiwan Market Applications

twstock addresses a specific gap for developers working with Taiwan securities: a Python-oriented interface for collecting data from the Taiwan Stock Exchange (TWSE) and the Taipei Exchange (TPEX). It covers stock price history, daily trading fields, security-code metadata, realtime information, and calculations based on price and volume. The README describes it as a recreation of the functionality of toomore/grs, so the package is aimed at people who need a direct Python library rather than a general-purpose financial platform.

The package targets developers building scripts, data-processing jobs, monitoring tools, or educational examples around Taiwanese securities. A basic Stock object is initialized with a code such as '2330'. The documented data model includes date, capacity, turnover, open, high, low, close, change, and transaction. That structure makes the result usable for analysis code, but the README does not document authentication, commercial entitlements, historical-data guarantees, or production service levels.

The distinction between historical and realtime data matters. Historical methods operate on collected daily records, while twstock.realtime.get retrieves current information for one or several codes. The documentation does not promise that both paths use identical fields, timestamps, or availability guarantees. An application should therefore model realtime responses separately from daily records unless its own validation establishes otherwise.

## Stock Records, Indicators, and Best Four Point Logic

The main analysis path is built around Stock and its moving-average, continuous, and bias-ratio methods. The README shows a five-day moving average for price, a five-day moving average for capacity, a continuous calculation over the moving-average series, and a bias-ratio comparison between five-day and ten-day periods. These are local transformations over retrieved data. The package does not claim that they are forecasts, and the Best Four Point output should be read as a documented rule-based classification rather than an investment recommendation.

BestFourPoint wraps a Stock instance and exposes methods for buying, selling, and combined analysis. The CLI example prints classifications such as "Buy" and "Sell" with short explanations, including volume and moving-average conditions. This gives command-line users a quick way to inspect a code without writing analysis code. The exact rules are implemented in the package, but the README excerpt does not reproduce their full threshold table, so users who need an auditable trading policy should inspect the source before depending on every classification.

The API also exposes the underlying arrays through properties such as price and capacity. This is convenient for custom calculations, but downstream code must handle missing, short, or unexpected series. The README shows no explicit exception contract for these cases. Treat indicator results as dependent on the quality and length of retrieved records rather than as self-validating results.

## Installation Paths Supported by twstock

The package can be installed from PyPI, cloned from GitHub, or installed from the source tree with flit. The project metadata in pyproject.toml requires Python 3.10 or newer and declares requests>=2.33.0 and lxml as dependencies. The README also lists Python 3, lxml, and requests as requirements. The following command is the documented PyPI installation path and installs the package into the current user's Python environment:

```bash
$ python -m pip install --user twstock
```

After installation, the README presents Stock analysis as the first real use. The example retrieves TSMC, calculates price and capacity moving averages, calculates how long the price average has continued, and calculates a five-day versus ten-day bias ratio:

```python
from twstock import Stock

stock = Stock('2330')
ma_p = stock.moving_average(stock.price, 5)
ma_c = stock.moving_average(stock.capacity, 5)
ma_p_cont = stock.continuous(ma_p)
ma_br = stock.ma_bias_ratio(5, 10)
```

The first use depends on the upstream data source responding successfully. It is not an offline sample-data workflow, because Stock('2330') is documented as retrieving stock prices. A failed source request or insufficient historical observations can therefore affect whether the example produces meaningful indicator values.

## Realtime Quotes, Security Codes, and Proxy Configuration

twstock provides separate entry points for realtime quotes and the securities-code registry. Realtime retrieval can request one code or a list of codes:

```python
import twstock

twstock.realtime.get('2330')
twstock.realtime.get(['2330', '2337', '2409'])
```

The README does not specify the full realtime response schema in this excerpt, so applications should inspect the returned object rather than assume that it matches Stock.data. That separation also prevents a caller from confusing a current quote with a completed daily record without validating timestamps and fields.

Security metadata can be accessed through twstock.codes. The registry includes fields such as type, code, name, ISIN, start date, market, group, and CFI. The README says that first use should update the TWSE and TPEX code lists, either through the CLI or by calling twstock.__update_codes(). The documented command is:

```bash
$ twstock -U
Start to update codes
Done!
```

The corresponding Python call is:

```python
import twstock
twstock.__update_codes()
```

Proxy support is built on requests proxies. SingleProxyProvider accepts one proxy mapping, while RoundRobinProxiesProvider cycles through multiple mappings. The README documents configuring these providers with twstock.proxy.configure_proxy_provider, then replacing the provider's proxies list when the mapping changes. This is useful in restricted network environments, but proxy availability and upstream access remain external dependencies.

## Upstream Request Limits and Source Reliability

The clearest operational limitation is the TWSE request limit documented in the README: three requests every five seconds. Exceeding that limit can result in a ban. This is not merely a performance concern. A collection job that requests many securities or refreshes data too frequently may stop receiving valid responses. The package does not document a built-in scheduler, retry budget, ban recovery procedure, or guaranteed throttling policy in the README, so those responsibilities remain with the application or caller.

The data also comes from external TWSE and TPEX endpoints. The README does not state how quickly the package adapts when an upstream page changes, how source outages are represented, or whether historical data is corrected after later revisions. Realtime data carries a different risk profile from historical records because it changes continuously and may be unavailable outside market conditions.

An integration should treat each response as untrusted input, validate the expected code and date, and record retrieval failures. Those are application responsibilities rather than documented twstock guarantees. The repository includes a test directory and lists vcrpy among its development dependencies, but the README does not claim that live upstream behavior is continuously monitored or that every exchange response format is protected against future changes.

## twstock Compared with Direct TWSE and TPEX Integration

The main alternative is to integrate the TWSE and TPEX endpoints directly, using Python's requests or lxml or another HTTP and parsing stack. Direct integration gives the developer full control over request timing, headers, response parsing, caching, retries, and the representation of source fields. It also means more code and more responsibility for understanding each upstream response format.

twstock reduces that work by supplying a Python Stock interface, code metadata, indicators, a BestFourPoint abstraction, realtime methods, and proxy provider classes. That convenience is valuable when the application only needs the package's documented abstractions. It is less suitable when an application requires exchange-specific fields that Stock does not expose or needs precise control over the exchange request schedule.

The choice is therefore between a library-level abstraction and endpoint-level integration. twstock is not documented as a separate market-data provider. It retrieves data associated with TWSE and TPEX and parses that material for Python callers. An application with unusual exchange behavior or strict audit requirements may prefer direct integration, while a small script can benefit from twstock's higher-level methods and command-line entry point.

## Maintenance, Releases, and MIT Upgrade Considerations

The repository is not archived, and the last push was on 2026-06-23. Recent releases listed in the project information include v1.5.1 on 2026-04-23, v1.5.0 on 2026-04-09, and v1.4.6 on 2026-04-09. The repository layout includes CI-related files, tests, a Pipfile, uv.lock, pyproject.toml, and flit configuration, indicating that the package has release and development infrastructure beyond the README examples.

The package is distributed under the MIT License. The license metadata in pyproject.toml identifies the project as MIT, and the repository includes a LICENSE file. The practical upgrade cost depends on Python version requirements, dependency compatibility, and any changes in exchange response formats. pyproject.toml requires Python >=3.10 and requests>=2.33.0, so an upgrade can require changes to the runtime or dependency environment before application code changes.

The README does not document a formal deprecation policy, compatibility matrix for older Python releases, or a release-to-release migration guide. Users should check pyproject.toml and release notes when upgrading rather than assuming that historical examples remain unchanged. The MIT license permits use and modification under its conditions, but users remain responsible for reviewing the actual LICENSE text and any separate terms associated with the upstream data sources.

## Conclusion

Adopt twstock when a Python application needs Taiwan stock metadata, historical price data, realtime quotes, or the documented Best Four Point checks. Do not treat its signals as a complete trading system. Verify Python compatibility, upstream request limits, data freshness, and proxy requirements before integrating it.

## FAQ

### How do I install twstock for Python?

The README documents installing it from PyPI with `python -m pip install --user twstock`. It also documents cloning the repository and installing from source. pyproject.toml requires Python 3.10 or newer.

### How do I fetch realtime Taiwan stock information with twstock?

Use `twstock.realtime.get('2330')` for one code or pass a list such as `['2330', '2337', '2409']` for several codes. The README does not specify the complete realtime response schema.

### What are the main limitations of twstock?

TWSE imposes a documented limit of three requests every five seconds, and exceeding it can cause a ban. The README also does not document guarantees for upstream availability, realtime data freshness, retries, or a production service-level agreement.

## Sources

- [License: MIT](https://github.com/mlouielu/twstock/blob/dev/LICENSE)
- [mlouielu/twstock on GitHub](https://github.com/mlouielu/twstock)
- [Project website](http://twstock.readthedocs.io/)
- [README](https://github.com/mlouielu/twstock/blob/dev/README.md)
- [Releases](https://github.com/mlouielu/twstock/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mlouielu-twstock