For implementation and code generation specification, check Implementation.

This is the structure of a minimal PureScript-Python project, for previewing.

This document is about how to call your PureScript project from Python.

Accurately, how to use Python code to call the Python package generated from your purescript project.

If you want, we could discuss questions, or interesting stuffs related to Python/PureScript/Static Typing.

At this Gitter Room .

1. *Installing a CPython distribution.

   If you're already a user of CPython, you can skip this step.

   Otherwise, go to this official download page, download and install any valid distribution(>=3.5).

2. Installing the Python package purescripto, which will provide you the command pspy.

   Possible commands for installing can be:

   # if `pip` is in PATH
   pip install -U purescripto
   # if `python` is in PATH
   python -m pip install -U purescripto
   # if `pip3` is the correct command to install pkgs to Python3
   pip3 install -U purescripto

3. Installing nodejs, which is distributed with a command npm, and use npm to install purescript and its package manager spago:

   npm install -g purescript
   npm install -g spago

   You might check PureScript: Getting Started for more details.

4. git clone https://github.com/purescript-python/purescript-python-ffi-index ~/.pspy/mirrors/default.

   If you're using windows, remember to expand the user directory "~" to "C:\Users\twshe<username>".

5. Create an empty folder called hello-world somewhere appropriate,get in, and call

   spago init  # init purescript project
   pspy --init # init purescript-python local configuration
   

6. Add a key backend with value "pspy", to file spago.dhall of your hello-world project. This is an example:

    {-
    Welcome to a Spago project!
    You can edit this file as you like.
    -}
    { name = "my-project"
    , dependencies = [ "console", "effect", "psci-support" ]
    , packages = ./packages.dhall
    , sources = [ "src/**/*.purs", "test/**/*.purs" ]
    , backend = "pspy" -- !!NOTE THIS!!
    }

7. Write your code in src/**.purs, and use spago run to execute your project(the default entry module is Main).

PureScript is close to Haskell, hence a Haskell user can pick it up in few seconds.

The home of PureScript is PureScript.org, where you can find things involving documentations.

A major motivation for my working on PureScript is its lightweighted but awesome IDE support.

For VSCode users, installing the plugin PureScript IDE and File -> Preferences -> Settings -> (search purescript) -> Turn on "Add Spago sources" will be sufficient. No need to install some GitHub repo and build for 4 hours! And this IDE feels swift!

For each project, if your project directory tree is

- src
    - Main.purs
    - Mod
        - A.purs

If you have foreign definitions in module Mod.A, you need to create a directory python-ffi juxtaposing src, and it'll finally look like:

- python-ffi
   - Mod
      - A.py
- src
    - Main.purs
    - Mod
        - A.purs

It's now under GNU LESSER GENERAL PUBLIC LICENSE.

There're some reasons for why I have to choose this:

To make releases more user-friendly, the purescript-python compiler is now distributing in the form of static-linked binaries, which could run perfectly in each Linux distribution.

However, to achieve this, a Linux binary distribution have to statically link to some essential Haskell dependencies like integer-GMP and glibc, which're under LGPL.

Hence, we cannot avoid LGPL trivially as the development of alternative libraries(integer-simple or musl/uClibc) are either suspended or WIP. So we change LICENSE to LGPL.

Fortunately, purescript-python is just a compiler, which actually means you don't need to statically link to it.

Similar cases are other LGPL compilers/transpilers, like gcc/pandoc. We know they didn't trouble us in terms of their licenses, so purescript-python would not as well.

If pspy-blueprint provided by the Python package purescripto didn't work(e.g., users of MacOSX < 10.15), you should manually install it from this repository, and currently there're 2 options:

1. Install from GitHub release page.
2. Install from source(Need Haskell stack): clone this repo, and use command stack install ., which will install pspy-blueprint to your .local PATH.

For Linux users, you might also need to use chmod u+x <path/to/pspy-blueprint> to allow the permission to execute.