2022年5月4日 星期三

CKAN Theming Tutorial 1(v2.9): 靜態檔案(圖片與CSS)

https://docs.ckan.org/en/2.9/theming/static-files.html

新增 CKAN 設定 extra_public_paths。plugin 可讓存放靜態檔案的目錄開放給 template 使用。以下以一個在首頁的 template 圖檔為例。

延續 CKAN templates Tutorial1(v2.9): 空的example_theme ,切換到 /usr/lib/ckan/default/src/ 目錄下。

public 目錄

將圖片與CSS 放在如下目錄:

ckanext-example_theme/
  ckanext/
     example_theme/
        public/
           ckan-logo.jpg
           example_theme.css


example_theme.css 檔內容:

.account-masthead {
    background-color: rgb(40, 40, 40);
}

420x220px ckan-logo.jpg

plugin.py 註冊 public 目錄

編輯 ckanext-example_theme/ckanext/example_theme/plugin.py,在 update_config() 中呼叫 add_public_directory() 向 CKAN 註冊 public 目錄:

    def update_config(self, config):
        略...

        # Add this plugin's public dir to CKAN's extra_public_paths, so
        # that CKAN will use this plugin's custom static files.
        toolkit.add_public_directory(config, 'public')

覆寫 base.html

在如下目錄新增 base.html:

ckanext-example_theme/
  ckanext/
    example_theme/
      templates/
        base.html

base.html 內容如下:

{% ckan_extends %}

{% block styles %}
  {{ super() }}
  <link rel="stylesheet" href="/example_theme.css" />
{% endblock %}

styles  block 中的內容會出現在HTML網頁的 <head>...</head> 中。

安裝

  1. 進入Python Virtual Environment: 
    . /usr/lib/ckan/default/bin/activate
  2. 切換目錄:
    cd /usr/lib/ckan/default/src/ckanext-example_theme
  3. 安裝 Plugin: 
    python setup.py develop
  4. 重啟 CKAN 服務:
    (production版) sudo supervisorctl restart ckan-uwsgi:*
    (develop版) ckan -c /etc/ckan/default/ckan.ini run

測試

http://[CKAN Website IP]/ckan-logo.jpg、http://[CKAN Website IP]/example_theme.css 可看到對應內容。

檢視 http://[CKAN Website IP] 的網頁原始碼,在HTML的 <head>...</head> 可發現:

<link rel="stylesheet" href="/example_theme.css" />




2022年5月3日 星期二

CKAN Extensions Tutorial 3(v2.9): 在 plugin 中呼叫 toolkit

https://docs.ckan.org/en/2.9/extensions/tutorial.html#using-the-plugins-toolkit

CKAN plugins toolkit 是一個 Python module,提供 CKAN 相關的 functions, classes 及 exceptions 協助撰寫 CKAN extension。

toolkit.get_action 可用來呼叫 CKAN 的 action function,這和透過 web interface 或 API 呼叫 的方法一樣。以下程式,ckan.plugins.toolkit.get_action 呼叫ckan.logic.action.get.member_list 取得 curators group 的成員名單,結果和 API 呼叫 /api/3/action/member_list 會是一樣的:

    members = toolkit.get_action('member_list')(
        data_dict={'id': 'curators', 'object_type': 'user'})


延續上個 CKACKAN Extensions Tutorial(v2.9): 實作 IAuthFunctions 自訂授權規則,以下將實作只允許 curators 群組成員建立群組的功能。

建立 curators 群組

在 CKAN 中建立 curators 群組。

修改 plugin.py:實作 IAuthFunctions

修改 ckanext-iauthfunctions/ckanext/iauthfunctions/plugin.py (程式碼)

import ckan.plugins as plugins
import ckan.plugins.toolkit as toolkit

def group_create(context, data_dict=None):

    # Get the user name of the logged-in user.
    user_name = context['user']

    # Get a list of the members of the 'curators' group.
    members = toolkit.get_action('member_list')(
        data_dict={'id': 'curators', 'object_type': 'user'})

    # 'members' is a list of (user_id, object_type, capacity) tuples, we're
    # only interested in the user_ids.
    member_ids = [member_tuple[0] for member_tuple in members]

    # We have the logged-in user's user name, get their user id.
    convert_user_name_or_id_to_id = toolkit.get_converter(
        'convert_user_name_or_id_to_id')
    user_id = convert_user_name_or_id_to_id(user_name, context)

    # Finally, we can test whether the user is a member of the curators group.
    if user_id in member_ids:
        return {'success': True}
    else:
        return {'success': False,
                'msg': 'Only curators are allowed to create groups'}

class ExmapleAuthFunctionsPlugin(plugins.SingletonPlugin):
    plugins.implements(plugins.IAuthFunctions)

    def get_auth_functions(self):
        return {'group_create': group_create}


  • 實作 IAuthFunctions
  • 覆寫 IAuthFunctions 介面的 get_auth_functions 方法
  • 呼叫 toolkit.get_action('member_list') 判斷目前使用者是否在 curators 群組

安裝

  1. 進入Python Virtual Environment: 
    . /usr/lib/ckan/default/bin/activate
  2. 切換目錄:
    cd /usr/lib/ckan/default/src/ckanext-iauthfunctions
  3. 安裝 Plugin: 
    python setup.py develop
  4. 重啟 CKAN 服務:
    sudo supervisorctl restart ckan-uwsgi:*

測試

  • 開 Postman 執行 api 呼叫
curl POST 'http://[CKAN web site]/api/3/action/group_create
--header 'Authorization: [測試會員的API Key]' 
--header 'Content-Type: application/json' 
--data-raw '{
    "name": "0506-Group",
    "owner_org": "0427-org",
    "description": "test ckanext-iauthfunctions"    
}'

視是否為 curators group 的帳號,success 回傳 true 或 false:

{
    "error": {
        "__type": "Authorization Error",
        "message": "拒絕存取: Only curators are allowed to create groups[ExampleIAuthFunctionsPlugin]"
    },
    "help": "...",
    "success": false
}
  • 以管理員登入 CKAN,建立 curators 群組
    • 把測試會員加入這個群組。
    • 再次以 Postman 執行以上 api 呼叫
    • 即可成功

CKAN Extensions Tutorial(v2.9): 實作 IAuthFunctions 自訂授權規則

https://docs.ckan.org/en/2.9/extensions/tutorial.html#implementing-the-iauthfunctions-plugin-interface

CKAN 提供許多 plugin interfaces(v2.9) 以便掛勾/hook 到 CKAN 修改或擴充功能:

  • u'Interface',
  • u'IRoutes',
  • u'IMapper',
  • u'ISession',
  • u'IMiddleware',
  • u'IAuthFunctions',
  • u'IDomainObjectModification',
  • u'IFeed',
  • u'IGroupController',
  • u'IOrganizationController',
  • u'IPackageController',
  • u'IPluginObserver',
  • u'IConfigurable',
  • u'IConfigurer',
  • u'IActions',
  • u'IResourceUrlChange',
  • u'IDatasetForm',
  • u'IValidators',
  • u'IResourcePreview',
  • u'IResourceView',
  • u'IResourceController',
  • u'IGroupForm',
  • u'ITagController',
  • u'ITemplateHelpers',
  • u'IFacets',
  • u'IAuthenticator',
  • u'ITranslation',
  • u'IUploader',
  • u'IBlueprint',
  • u'IPermissionLabels',
  • u'IForkObserver',
  • u'IApiToken',
  • u'IClick',

CKAN 如何驗證

參考: plugin interfaces。凡可透過 CKAN web 介面或 API 呼叫的動作都是以 ckan/logic/action/{create,delete,get,update}.py 實作的 action function。

例如資料集相關的 Web API 便對應到:

  • func:`ckan.logic.action.create.package_create`
  • func:`ckan.logic.action.get.package_show`
  • func:`ckan.logic.action.update.package_update`
  • func:`ckan.logic.action.delete.package_delete`

每個 action function 都有對應的 authorization function (ckan/logic/auth/{create,delete,get,update}.py),CKAN 呼叫 authorization function 決定使用者是否有被授權執行。

實作 ckan.plugins.interfaces.IAuthFunctions,並註冊與 CKAN 同名的 authorization function,如:'user_create', 'group_create',即可覆寫 CKAN 的授權規則。

在 CKAN 呼叫 authorization function 之前,會先驗證呼叫端是否提供合法的 API key。若要允許匿名執行, authorization function 需標示為 auth_allow_anonymous_access。如:

            @p.toolkit.auth_allow_anonymous_access
            def my_search_action(context, data_dict):
                略⋯⋯

IAuthFunctions

實作 ckan.plugins.interfaces.IAuthFunctions。所有 authorization function 都有兩個參數:

  • context
    • model: 可用來查詢資料庫
    • user: 內容使用者的 名稱/IP(匿名存取)
    • auth_user_obj: model.User物件/None(匿名存取)
  • data_dict
    • CKAN 會傳給所有 authorization and action functions data_dict,內容所有 post 進來的資料,可能是網頁中填寫的表單欄位內容,或 API 呼叫傳入的 JSON 內容如:
{'description': u'A really cool group',
 'image_url': u'',
 'name': u'my_group',
 'title': u'My Group',
 'type': 'group',
 'users': [{'capacity': 'admin', 'name': u'seanh'}]}

回傳 dictionary:

  • {'success': True} 授權
  • {'success': False} 拒絕

範例如下:

def user_create(context, data_dict=None):
  if (some condition):
    return {'success': True}
  else:
    return {'success': False, 'msg': 'Not allowed to register'}

CKAN Extensions Tutorial(v2.9):一個空的 CKAN extension

https://docs.ckan.org/en/2.9/extensions/tutorial.html

建立:ckan generate extension  

  1. 進入Python Virtual Environment:
    . /usr/lib/ckan/default/bin/activate
  2. 切換目錄
    cd /usr/lib/ckan/default/src 
  3. 執行 ckan generate extension

Extension's name [must begin 'ckanext-']: ckanext-你的extension名稱
(如: ckanext-iauthfunctions )]

├── ckanext
│   ├── iauthfunctions //Python package 程式碼目錄
│   │   ├── assets
│   │   │   └── webassets.yml
│   │   ├── fanstatic
│   │   ├── i18n
│   │   ├── __init__.py
│   │   ├── plugin.py //CKAN Extension的功能寫在這裡
│   │   ├── public
│   │   ├── templates
│   │   └── tests
│   │       ├── __init__.py
│   │       └── test_plugin.py
│   └── __init__.py
├── dev-requirements.txt
├── LICENSE
├── MANIFEST.in
├── README.md
├── requirements.txt
├── setup.cfg
├── setup.py  //用它安裝到Virtual Environment
└── test.ini

若出現錯誤 `cookiecutter` library is missing from import path.。則加裝 cookiecutter :

 pip install cookiecutter 

修改 plugin.py:撰寫 plugin 類別

修改 ckanext-iauthfunctions/ckanext/iauthfunctions/plugin.py。CKAN 的 extension 其實就是一個 plugin,所有 CKAN plugin 都需繼承自 plugins.SingletonPlugin:
 
import ckan.plugins as plugins

class ExampleIAuthFunctionsPlugin(plugins.SingletonPlugin):
    pass

修改 setup.py:設定 entry_points

修改 ckanext-iauthfunctions/setup.py 的 entry_points

entry_points='''
        [ckan.plugins] 
        example_iauthfunctions=ckanext.iauthfunctions.plugin:ExampleIAuthFunctionsPlugin

修改 ckan.ini:啟用 plugin

修改 /etc/ckan/default/ckan.ini。CKAN 的 extension plugins 必須加到 CKAN 設定檔的 ckan.plugins 中,CKAN 才會呼叫。

ckan.plugins = stats text_view 略... example_iauthfunctions

安裝測試

  1. 進入Python Virtual Environment: 
    . /usr/lib/ckan/default/bin/activate
  2. 切換目錄:
    cd /usr/lib/ckan/default/src/ckanext-iauthfunctions
  3. 安裝 Plugin: 
    python setup.py develop
  4. 重啟 CKAN 服務:
    sudo supervisorctl restart ckan-uwsgi:*

檢視錯誤

cat /etc/ckan/default/uwsgi.ERR

2022年4月26日 星期二

CKAN Get Started:CKAN API(v2.9)

Check CKAN API 玩一下它的 api。(把 JSON formatter plugin for Chrome 裝起來比較好看 JSON 資料)

Datasets 與 resources

在 CKAN,資料以 dataset 形式上傳。dataset 包含:

  • metadata
    說明資料,如:標題、出版者、日期...。
  • resource
    即資料本身。CKAN 不管格式,可以是 CSV, Excel, XML, PDF, RDF 或圖檔。
    CKAN 可將資料儲存在內部或僅儲存連結。
一個 dataset 可包含多個 resource,如歷年資料,或同樣的資料但不同的格式。

建立 Organizations, Datasets 及 Resources

有四個步驟:

  1. Get an API key (API Key 不等於 API Token)
  2. Create an organization;
  3. Create dataset inside an organization (dataset 一定掛在某個 organization 下);
  4. Add resources to the dataset

開個 Postman 執行以下 api 呼叫

Get

curl http://11.11.11.163/api/3/action/group_list

Create Organization

curl -X POST 'http://[你的IP]/api/3/action/organization_create'
-H 'Authorization: [你的API Key]'
-H 'Content-Type: application/json' 
-d '{
"name": "0509-org",
"title": "0509組織",
"description": "測試CKAN"
}'

Create Dataset

curl POST 'http://[你的IP]/api/3/action/package_create'
--header 'Authorization: [你的API Key]'
--header 'Content-Type: application/json'
--data-raw '{
"name": "0509-dataset",
"title": "0509 資料集",
"description": "測試CKAN",
"owner_org": "0509-org"
}'

Add a resource

curl POST 'http://[你的IP]/api/3/action/resource_create'
--header 'Authorization: [你的API Key]'
--header 'Content-Type: application/json'
--data-raw '{
"url": "https://raw.githubusercontent.com/frictionlessdata/test-data/master/files/csv/100kb.csv",
"description": "來自 githubusercontent frictionlessdata 的範例資料",
"name": "0509-daset-test-csv-data",
"owner_org": "0509-org",
"package_id": "0509-dataset"
}'


CKAN創始人Rufus Pollock:CKAN 概覽

Rufus Pollock,CKAN的創始人,著有 《The Open Revolution: Rewriting the Rules of the Information Age (2018) 》一書主張 Open Data(參考:Open (Public) Data: What, Why, How)。

以下為他在 CKAN Open Data Portal Webinar 中的介紹。(Webinar 的 Key Takeaways) 

CKAN Platform

CKAN 是 Data Management System (DMS) 。相對於 CMS 針對 content, DMS 的對象是 data。

CKAN 可以是以下解決方案的平台:

  • Data Portals:a gateway to data
  • Data Catalog
  • Data Lake:結合雲端儲存及運算能力。

CKAN Features

CKAN 許多功能 都可客制化。


CKAN 採元件化設計,各元件可單獨或組合使用。


CKAN 官方文件

2022年4月24日 星期日

Python Packages

https://data-flair.training/blogs/python-packages/

__init__.py

透過 __init__.py 檔案把一個目錄變為 Python package。

這個檔案可以是空的,也可用來放初始化程式。就讓__init__.py 空白也是不錯的做法。

Python Package Structure

Game 是 root package,底下有三個附屬 package: Sound, Image,  Level 和 __init__.py。Sound 底下有三個 module: load, play, and pause 和 __init__.py。

從 Packages 匯入/Import Modules

從 sound package 匯入load module:

import Game.Sound.load 

 或

from Game.Sound import load

或簡化為 loadgame

import Game.Sound.load as loadgame

或

loadgame=Game.Sound.load

如果 Sound subpackage 有個函式 volume_up(),則可以下方式呼叫:

loadgame.volume_up(7)


如果用以下方式直接匯入函式並別名為 volup():

from Game.Sound.load import volume_up() as volup

便可更簡單的呼叫:

volup(7)

不匯入子目錄

只匯入指定 package 目錄下的內容,不含其子目錄。

Create Python Package


在這個 Package 底下加入一個檔案 utilities.py:

def get_total_employees():
          print("100 employees.")

在 PythonPackagesDemo.py 裡可呼叫:

import hr.utilities
HR.Utilities.get_total_employees()